doc-content/apache-kie-kogito/src/main/asciidoc/creating-running/chap-kogito-creating-running.adoc

[id="chap-kogito-creating-running"]
= Creating and running your first {PRODUCT} services
ifdef::context[:parent-context: {context}]
:context: kogito-creating-running

// Purpose statement for the assembly
[role="_abstract"]
As a developer of business processes and decisions, you can use {PRODUCT} business automation to build  cloud-native applications that adapt to your business domain and tooling.

.Prerequisites
* JDK 17 is installed.
* Apache Maven 3.9.6 is installed.

[id="con-kogito-automation_{context}"]
== {PRODUCT} business automation

[role="_abstract"]
{PRODUCT} 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 {OPENSHIFT} as the target cloud platform for {PRODUCT}, and to the Knowledge Is Everything (KIE) open source business automation project from which {PRODUCT} originates.

{PRODUCT} is optimized for a hybrid cloud environment and adapts to your domain and tooling needs. The core objective of {PRODUCT} is to help you mold a set of business processes and decisions into your own domain-specific cloud-native set of services.

.Business processes and decisions to cloud services
image::kogito/creating-running/kogito-assets-to-cloud_enterprise.png[Image of business assets moving to cloud services]

When you use {PRODUCT}, you are building a cloud-native application as a set of independent domain-specific services to achieve some business value. The processes and decisions that you use to describe the target behavior are executed as part of the services that you create. The resulting services are highly distributed and scalable with no centralized orchestration service, and the runtime that your service uses is optimized for what your service needs.

If you need long-lived processes, you can persist the runtime state externally in a data grid such as Infinispan or the provided Data Index service. Each {PRODUCT} service also produces events that can be consumed by other services. For example, if you use Apache Kafka, events can be aggregated and indexed in a data index service, offering advanced query capabilities through GraphQL.

{PRODUCT} includes components that are based on well-known business automation KIE projects, specifically https://drools.org[Drools], https://jbpm.org[jBPM], and https://optaplanner.org[OptaPlanner], to offer dependable open source solutions for business rules, business processes, and constraint solving.

=== Cloud-first priority

{PRODUCT} is designed to run and scale on a cloud infrastructure. You can use {PRODUCT} with the latest cloud-based technologies, such as Quarkus, Knative, and Apache Kafka, to increase start times and instant scaling on container application platforms, such as {OPENSHIFT}.

.Technologies used with {PRODUCT}
image::kogito/creating-running/kogito-related-technolgies_enterprise.png[Image of cloud-based technologies]

For example, {PRODUCT} is compatible with the following technologies:

* *{OPENSHIFT}*, based on Kubernetes, is the target platform for building and managing containerized applications.
* *Quarkus* is native Java stack for Kubernetes that you can use to build applications with {PRODUCT} services.
* *Spring Boot* is also supported with {PRODUCT} so that you can use the Spring Framework with {PRODUCT}.
ifdef::KOGITO-COMM[]
* *GraalVM* with Quarkus enables you to use native compilation with {PRODUCT}, resulting in fast start-up times and minimal footprint. For example, a native {PRODUCT} service starts in about 0.003ms, about 100 times faster than a non-native start-up. Fast start-up is almost a necessity in a cloud ecosystem, especially if you need small serverless applications.
endif::[]
* *Knative* enables you to build serverless applications with {PRODUCT} that you can scale up or down (to zero) as needed.
* *Prometheus* and *Grafana* are compatible with {PRODUCT} services for monitoring and analytics with optional extensions.
* *Infinispan* and *MongoDB* are middleware technologies that {PRODUCT} supports for persistence.
* *Kafka* and *Keycloak* are middleware technologies that {PRODUCT} supports for messaging and security.

=== Domain-specific flexibility

{PRODUCT} adapts to your business domain instead of forcing you to modify your domain to work with {PRODUCT}. You can expose your {PRODUCT} services with domain-specific APIs, based on the processes and decisions that you have defined. Domain-specific APIs for {PRODUCT} services do not require third-party or internal APIs.

For example, a process for onboarding employees could generate remote REST API endpoints that you can use to onboard new employees or get information on their status, all using domain-specific JSON data.

.Example custom API endpoints in Swagger
image::kogito/creating-running/kogito-domain-api-endpoints-example.png[Image of REST API endpoints in Swagger UI]

You can also expose domain-specific data through events or in a data index so that the data can be consumed and queried by other services.

=== Developer-centered experience

Another focus of {PRODUCT} is optimal developer experience. You can use much or all of your existing tooling and workflow to develop, build, and deploy {PRODUCT} services, whether locally for testing or into the cloud. Quarkus offers development-mode features to help with local testing, such as live reload of your processes and decisions in your running applications for advanced debugging.

{PRODUCT} tooling is embeddable so that you can continue using the workflow you already use for cloud-native services. For example, the *{VSCODE_EXTENSION}* VSCode extension enables you to edit your Business Process Model and Notation (BPMN) 2.0 business processes and Decision Model and Notation (DMN) decision models directly in your VSCode IDE, next to your other application code.

.Building a {PRODUCT} process service in VSCode
image::kogito/creating-running/kogito-run-quarkus-devmode-demo.gif[Demo of {PRODUCT} BPMN2 extension in VSCode]

[id="con-kogito-quarkus-springboot_{context}"]
=== {PRODUCT} on Quarkus and Spring Boot

[role="_abstract"]
The primary Java frameworks that {PRODUCT} supports are Quarkus (recommended) and Spring Boot.

https://quarkus.io/[Quarkus] is a Kubernetes-native Java framework with a container-first approach to building Java applications, especially for Java virtual machines (JVMs) such as GraalVM and HotSpot. 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 {PRODUCT} services, Quarkus is the preferred framework for optimal Kubernetes compatibility and enhanced developer features, such as live reload in development mode for advanced debugging.

https://spring.io/projects/spring-boot[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 {PRODUCT} services, Spring Boot is supported for developers who need to use {PRODUCT} in an existing Spring Framework environment.

[id="ref-kogito-app-examples_{context}"]
== Example applications with {PRODUCT} services

[role="_abstract"]
{PRODUCT} includes example applications in the https://github.com/apache/incubator-kie-kogito-examples[`kogito-examples`] repository in GitHub. These example applications contain various types of {PRODUCT} services on Quarkus or Spring Boot to help you develop your own applications. The services use one or more Business Process Model and Notation (BPMN) process models, Decision Model and Notation (DMN) decision models, Drools Rule Language (DRL) rule units, XLS spreadsheet decision tables, 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: In the https://github.com/apache/incubator-kie-kogito-examples[`{PRODUCT_INIT}-examples`] repository in GitHub, the example applications in the default `stable` branch use the latest version of {PRODUCT}. 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 Quarkus, Spring Boot, and docker-compose where applicable.

The following list describes some of the examples provided with {PRODUCT}:

Decision services::
* `dmn-quarkus-example` and `dmn-springboot-example`: A decision service (on 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 Quarkus with a single DRL rule unit.
* `ruleunit-quarkus-example` and `ruleunit-springboot-example`: A decision service (on 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-event-driven-quarkus` and `dmn-event-driven-springboot`: A DMN decision service on Quarkus and Spring Boot that demonstrates the capability of the {PRODUCT} Event-Driven decisions add-on.

Decision services that use the {PRODUCT} Trusty Service and Explainability Service::
* `dmn-tracing-quarkus`: A DMN decision service on Quarkus that uses the `kie-addons-quarkus-tracing-decision` add-on to generate tracing events that the {PRODUCT} Trusty Service and Explainability Service can consume and expose.

Process services::
* `process-quarkus-example` and `process-springboot-example`: A process service (on Quarkus or Spring Boot) for ordering items and that exposes REST operations to create new orders or to list and delete active orders.
* `onboarding-example`: A combination of a process service and two decision services that use DMN and DRL for onboarding new employees.
* `flexible-process-quarkus` and `flexible-process-springboot`: A process service (on Quarkus or Spring Boot) that uses flexible processes for case management in {PRODUCT}.
* `process-springboot-example`: A process service on Spring Boot for ordering items using add-ons.
* `process-usertasks-with-security-oidc-quarkus-with-console`: A quickstart project using add-ons to show typical user task orchestration.

Process services that use Decision services::
* `process-decision-quarkus`: A process service integrated with decisions services, using an embedded method, in which business rule tasks are used for communication. The decisions are declared with DMN and DRL.
* `process-decision-rest-quarkus`: A process service integrated with decisions services, using REST endpoints for remote communication. The decisions are declared with DMN and DRL.

Process services for OpenShift deployment::
* `kogito-travel-agency`: A combination of process services and decision services that use DRL and XLS for travel booking, intended for deployment on {OPENSHIFT}.

Process services that use MongoDB::
* `process-mongodb-persistence-quarkus` and `process-mongodb-persistence-springboot`: A quickstart project on (Quarkus and Spring Boot) using add-ons that process deals for travelers using MongoDB.

[id="proc-kogito-app-examples-running_{context}"]
=== Running the {PRODUCT} example applications

[role="_abstract"]
To get started quickly with {PRODUCT}, you can run any of the example applications in the https://github.com/apache/incubator-kie-kogito-examples[`kogito-examples`] repository in GitHub and experiment with the {PRODUCT} services.

For this procedure, use the https://github.com/apache/incubator-kie-kogito-examples/tree/stable/process-quarkus-example[`process-quarkus-example`] or https://github.com/apache/incubator-kie-kogito-examples/tree/stable/process-springboot-example[`process-springboot-example`] application. You can follow similar steps with the other {PRODUCT} examples on Quarkus or Spring Boot.

In the `process-quarkus-example` and `process-springboot-example` applications, the `orders.bpmn2` process describes the steps that need to be followed when ordering items. The process includes a script task for writing debug information and a call activity for invoking a subprocess, using a custom `Order` data object.

.Example `orders.bpmn2` process
image::kogito/creating-running/bpmn-model-example-orders.png[Image of `orders.bpmn` example process]

The `Add items` subprocess invokes the following `orderItems.bpmn2` process, which uses a `CalculationService.calculateTotal` custom Java service and a user task to verify the order.

.Example `orderItems.bpmn2` process invoked as a subprocess
image::kogito/creating-running/bpmn-model-example-order-items.png[Image of `orderItems.bpmn` example process]

The `persons.bpmn2` process invokes a Drools Rule Language (DRL) rule unit in a business rule task to determine customer age, followed by a user task for special handling requirements for children, if applicable.

.Example `persons.bpmn2` process invoked as a subprocess
image::kogito/creating-running/kogito-bpmn-example-person.png[Image of `persons` process diagram]

Based on these processes and on application configurations, this example service exposes REST operations to create new orders, to list and delete active orders, and to determine the age of a specified person.

.Procedure
. Download the latest https://github.com/apache/incubator-kie-kogito-examples/releases[`kogito-examples`] release to a local directory and extract the file.
. In a command terminal, navigate to the extracted `kogito-examples-__RELEASE__/process-__PLATFORM__-example` folder, and enter one of the following commands to build and run the example.
+
--
Quarkus and Spring Boot support the following run modes:

* *Development mode*: For local testing. On Quarkus, development mode also offers live reload of your processes and decisions in your running applications for advanced debugging.
* *JVM mode*: For compatibility with a Java virtual machine (JVM).
* *Native mode*: (Quarkus only, requires GraalVM or Mandrel) For direct binary execution as native code.

The command that you use depends on your preferred run mode and application environment:

* For development mode:
+
.On Quarkus
[source]
----
$ mvn clean compile quarkus:dev
----
+
.On Sprint Boot
[source]
----
$ mvn clean compile spring-boot:run
----
+
* For JVM mode:
+
.On Quarkus
[source]
----
$ mvn clean package
$ java -jar target/quarkus-app/quarkus-run.jar
----
+
.On Spring Boot
[source]
----
$ mvn clean package
$ java -jar target/sample-kogito-1.0-SNAPSHOT-runner.jar
----
+
ifdef::KOGITO-COMM[]
* For native mode (requires GraalVM or Mandrel):
+
.On Quarkus only
[source]
----
$ mvn clean package -Dnative
$ ./target/sample-kogito-1.0-SNAPSHOT-runner
----
+
endif::[]
--
. After the {PRODUCT} service is running, 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/`
* *HTTP headers*: For `POST` and `PUT` requests only:
** `accept`: `application/json`
** `content-type`: `application/json`
* *HTTP methods*: `GET`, `POST`, `PUT` or `DELETE`

.Example POST request body to create an order (JSON)
[source,json]
----
{
  "approver": "john",
  "order": {
    "orderNumber": "12345",
    "shipped": false
  }
}
----

.Example curl command to create an order
[source]
----
curl -X POST http://localhost:8080/orders -H 'content-type: application/json' -H 'accept: application/json' -d '{"approver" : "john", "order" : {"orderNumber" : "12345", "shipped" : false}}'
----

.Example response (JSON)
[source,json]
----
{
  "approver": "john",
  "id": "6b53c227-6d5e-40b7-8c8c-a541a2a47d58",
  "order": {
    "orderNumber": "12345",
    "shipped": false,
    "total": 0.3845152065899532
  }
}
----

.Swagger UI to interact with all application endpoints (such as \http://localhost:8080/q/swagger-ui or \http://localhost:8080/swagger-ui.html)
image::kogito/creating-running/kogito-swagger-example-jbpm.png[Image of Swagger UI for example application]

NOTE: For the predefined {PRODUCT} example applications, the Swagger UI for interacting with service endpoints is available only on Quarkus examples that you run in
development mode or in native mode.

This example procedure uses the following curl commands for convenience:

* Create an order:
+
.Example request
[source]
----
curl -X POST http://localhost:8080/orders -H 'content-type: application/json' -H 'accept: application/json' -d '{"approver" : "john", "order" : {"orderNumber" : "12345", "shipped" : false}}'
----
+
.Example response
[source]
----
{"approver":"john","id":"6b53c227-6d5e-40b7-8c8c-a541a2a47d58","order":{"orderNumber":"12345","shipped":false,"total":0.3845152065899532}}
----
+
The new order has an `"id"` field with a generated UUID that you can use to retrieve details about this specific order, if needed.

* View active orders:
+
.Example request
[source]
----
curl -X GET http://localhost:8080/orders -H 'content-type: application/json' -H 'accept: application/json'
----
+
.Example response
[source]
----
[{"approver":"john","id":"6b53c227-6d5e-40b7-8c8c-a541a2a47d58","order":{"orderNumber":"12345","shipped":false,"total":0.3845152065899532}}]
----

* View order details using the returned UUID:
+
.Example request
[source]
----
curl -X GET http://localhost:8080/orders/6b53c227-6d5e-40b7-8c8c-a541a2a47d58 -H 'content-type: application/json' -H 'accept: application/json'
----
+
.Example response
[source]
----
{"approver":"john","id":"6b53c227-6d5e-40b7-8c8c-a541a2a47d58","order":{"orderNumber":"12345","shipped":false,"total":0.3845152065899532}}
----
+
You use the `"id"` value for the order that was returned when you created the order or when you retrieved active orders.

* Cancel the order using the returned UUID:
+
.Example request
[source]
----
curl -X DELETE http://localhost:8080/orders/6b53c227-6d5e-40b7-8c8c-a541a2a47d58 -H 'content-type: application/json' -H 'accept: application/json'
----
--

[id="proc-kogito-app-examples-with-console-running_{context}"]
=== Interacting with {PRODUCT} Management and Task Console using example applications

You can interact with the {PRODUCT} Management and Task Console to run the processes using the example applications in the https://github.com/apache/incubator-kie-kogito-examples[`kogito-examples`] repository in GitHub. The example applications containing the `with-consoles` suffix, allow you to experiment with the {PRODUCT} services and {PRODUCT} Management and Task Console.

The Management and Task Console need to interact with the {PRODUCT} Data Index service using minimal persistence configuration, which you can perform using docker-compose configuration. The example applications provide docker-compose configuration to configure and start the required services, including Kafka, Infinispan, {PRODUCT} Data Index, {PRODUCT} Management Console, and {PRODUCT} Task Console.

.Default services started by docker-compose 'with-console' example applications
image::kogito/creating-running/docker-compose.png[Image of default services started by docker-compose 'with-console' examples]

NOTE: In each example application, the docker-compose starts the needed services to run the project. The docker-compose also configures additional services such as Keycloak (process-usertasks-with-security-oidc-PLATFORM-with-console) or {PRODUCT} Jobs (process-usertasks-timer-quarkus-with-console).

.Procedure
. Download the latest https://github.com/apache/incubator-kie-kogito-examples/releases[`kogito-examples`] release to a local directory and extract the file.
. In a command terminal, navigate to the extracted `kogito-examples-__RELEASE__/process-usertask-PLATFORM__-with-console` folder
. Compile the project to generate the persistence file descriptor, which docker-compose uses.
. From the docker-compose folder, execute `./startServices.sh` to start the containers with the services needed in each case.
. Enter one of the following commands to build and run the example:
+
--
Quarkus and Spring Boot support the following run modes:

* *Development mode*: For local testing. On Quarkus, development mode also offers live reload of your processes and decisions in your running applications for advanced debugging.
* *JVM mode*: For compatibility with a Java virtual machine (JVM).
ifdef::KOGITO-COMM[]
* *Native mode*: (Quarkus only, requires GraalVM or Mandrel) For direct binary execution as native code.
endif::[]

The command that you use depends on your preferred run mode and application environment:

* For development mode:
+
.On Quarkus
[source]
----
$ mvn clean compile quarkus:dev
----
+
.On Sprint Boot
[source]
----
$ mvn clean compile spring-boot:run
----
+
* For JVM mode:
+
.On Quarkus
[source]
----
$ mvn clean package
$ java -jar target/quarkus-app/quarkus-run.jar
----
+
.On Spring Boot
[source]
----
$ mvn clean package
$ java -jar target/sample-kogito-1.0-SNAPSHOT-runner.jar
----
+
ifdef::KOGITO-COMM[]
* For native mode (requires GraalVM or Mandrel):
+
.On Quarkus only
[source]
----
$ mvn clean package -Dnative
$ ./target/sample-kogito-1.0-SNAPSHOT-runner
----
+
endif::[]
--
. When the {PRODUCT} service is running, use a REST client, curl utility, or the Swagger UI (if configured for the application) to start a new request.
. Use the {PRODUCT} Management console to see the created process instance available by default at `http://localhost:8280`.
. Use the {PRODUCT} Task console available by default at `http://localhost:8380` to execute the user tasks.

In case some ports need to be changed, you can find the configuration of the containers in the `docker-compose/docker-compose.yml` file.

[id="con-kogito-modelers_{context}"]
== {PRODUCT} BPMN and DMN modelers

[role="_abstract"]
{PRODUCT} provides the following extensions or applications that you can use to design Business Process Model and Notation (BPMN) process models and Decision Model and Notation (DMN) decision models for your {PRODUCT} services using graphical modelers.

* *{VSCODE_EXTENSION} VSCode extension*: (Recommended) Enables you to view and design BPMN models, DMN models, and test scenario files in Visual Studio Code (VSCode). The VSCode extension in the {PRODUCT} requires VSCode .
+
To install the *{VSCODE_EXTENSION} VSCode extension* extension select the *Extensions* menu option in VSCode and search for and install the *{VSCODE_EXTENSION}* extension.
* *{CHROME_EXTENSION} Chrome extension*: Enables you to view and design BPMN and DMN models in GitHub repositories in Google Chrome.
+
To install the {CHROME_EXTENSION} Chrome extension search its name on https://chromewebstore.google.com/. Alternatively, build the package https://github.com/apache/incubator-kie-tools/blob/main/packages/chrome-extension-pack-kogito-kie-editors locally, and then in the upper-right corner in Chrome, go to *Customize and control* -> *Settings* -> *Extensions* -> *Load unpacked* and open the extracted `dist` folder.
* *Apache KIE™ Sandbox*: Enables you to view and design BPMN and DMN models online at `https://sandbox.kie.org/`.
* *BPMN and DMN Standalone Editors*: Enable you to view and design BPMN and DMN models embedded in your web applications. To download the necessary files, you can use the NPM artifacts from the https://www.npmjs.com/package/@kie-tools/kie-editors-standalone[Apache KIE™ repository].



[id="proc-kogito-vscode-extension_{context}"]
=== Installing the {VSCODE_EXTENSION} VSCode extension

[role="_abstract"]
VSCode is the preferred integrated development environment (IDE) for developing {PRODUCT} services. {PRODUCT} provides a *{VSCODE_EXTENSION}* 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. {PRODUCT} also provides individual *DMN Editor* and *BPMN Editor* VSCode extensions for DMN or BPMN support only, if needed.

.Prerequisites
* https://code.visualstudio.com/[VSCode]  is installed.

.Procedure
. In your VSCode IDE, select the *Extensions* menu option and search for *{VSCODE_EXTENSION}* 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.
. When the {PRODUCT} extension appears in the extension list in VSCode, select it and click *Install*.
. 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}* VSCode extension bundle, any `.dmn` or `.bpmn2` files that you open in VSCode are automatically displayed as graphical models. Additionally, any `.scesim` files that you open are automatically displayed as tabular test scenario models for testing the functionality of your business decisions.

If the {PRODUCT} 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.

[id="proc-kogito-standalone-editors_{context}"]
=== Configuring the {PRODUCT} standalone editors

[role="_abstract"]
The {PRODUCT} standalone editors are distributed in a self-contained library that provides 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:

* Use hosted JavaScript files directly
* Download each JavaScript file manually
* Use the NPM package

.Procedure
. Install the {PRODUCT} standalone editors using one of the following methods:
+
--
*Use hosted JavaScript files directly*: For this method, add the following `<script>` tags to your HTML page:

.Script tags for your HTML page
[source]
----
<script src="https://kiegroup.github.io/kogito-online/standalone/dmn/index.js"></script>
<script src="https://kiegroup.github.io/kogito-online/standalone/bpmn/index.js"></script>
----

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

.. Download the JavaScript files:
** For the DMN editor, go to https://kiegroup.github.io/kogito-online/standalone/dmn/index.js.
** For the BPMN editor, go to https://kiegroup.github.io/kogito-online/standalone/bpmn/index.js.
.. Add the downloaded Javascript files to your hosted application.
.. Add the following `<script>` tag to your HTML page:
+
.Script tag for your HTML page
[source]
----
<script src="https://<YOUR_PAGE>/dmn/index.js"></script>
----

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

.. Go to the https://www.npmjs.com/package/@kie-tools/kie-editors-standalone[Apache KIE™ repository] in NPM and download the NPM package.
.. Add the NPM package to your `package.json` file:
+
.Adding the NPM package
[source]
----
npm install @kie-tools/kie-editors-standalone
----
.. Import each editor library to your TypeScript file:
+
.Importing each editor
[source]
----
import * as DmnEditor from "@kie-tools/kie-editors-standalone/dist/dmn"
import * as BpmnEditor from "@kie-tools/kie-editors-standalone/dist/bpmn"
----
--
. 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
[source,java]
----
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:

.Example parameters
[cols="40%,60%", options="header"]
|===
|Parameter
|Description

|`container`
|HTML element in which the editor is appended.

|`initialContent`
a|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)
a|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)
a|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.

.Returned object methods
[cols="40%,60%", options="header"]
|===
|Method
|Description

|`getContent(): Promise<string>`
|Returns a promise containing the editor content.

|`setContent(path: string, 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 https://github.com/kiegroup/kie-tools/blob/master/packages/envelope-bus/src/api/index.ts#L43-L56[MessageBusClientApi] and https://github.com/kiegroup/kie-tools/blob/master/packages/editor/src/api/KogitoEditorEnvelopeApi.ts#L34-L41[KogitoEditorEnvelopeApi].
|===
--

[id="proc-kogito-creating-project_{context}"]
== Creating a Maven project for a {PRODUCT} service

[role="_abstract"]
Before you can begin developing {PRODUCT} services, you need to create a Maven project where you can build your {PRODUCT} assets and any other related resources for your application.

.Procedure
. In a command terminal, navigate to a local folder where you want to store the new {PRODUCT} project.
. Enter the following command to generate a project within a defined folder:
+
--
.On Quarkus
[source,subs="attributes+"]
----
$ mvn io.quarkus:quarkus-maven-plugin:create \
    -DprojectGroupId=org.acme -DprojectArtifactId=sample-kogito \
    -DprojectVersion=1.0.0-SNAPSHOT -Dextensions=kogito-quarkus
----

Alternatively, you can generate a project using the https://code.quarkus.io/?e=org.kie.kogito%3Akogito-quarkus[Quarkus website].
////
@comment: The following standard command for Quarkus isn't working currently but may be restored for Dev Preview

mvn io.quarkus:quarkus-maven-plugin:create -DprojectGroupId=com.company -DprojectArtifactId=sample-kogito -Dextensions="kogito"
////

[id="proc-kogito-creating-project-spring-boot_{context}"]
.On Spring Boot
[source,subs="attributes+"]
----
$ mvn archetype:generate \
    -DarchetypeGroupId=org.kie.kogito \
    -DarchetypeArtifactId=kogito-spring-boot-archetype \
    -DgroupId=org.acme -DartifactId=sample-kogito \
    -DarchetypeVersion={COMMUNITY_VERSION_FINAL} \
    -Dversion=1.0-SNAPSHOT
----

These commands generate a `sample-kogito` Maven project and import the {PRODUCT} extension for all required dependencies and configurations to prepare your application for business automation.
--
. Open or import the project in your VSCode IDE to view the contents.

[id="proc-customizing-spring-boot-project-creation_{context}"]
=== Creating a custom {PRODUCT} Spring Boot project

With Spring Boot, you can create custom Maven projects using {PRODUCT} Spring Boot archetype. This archetype enables adding {PRODUCT} Spring Boot starters or add-ons in the project creation. The {PRODUCT} Spring Boot starters include:

* `decisions`
* `processes`
* `rules`
* `predictions`

.Procedure
. In a command terminal, navigate to a local folder where you want to store the new {PRODUCT} project.
. Enter any of the following command to generate a project using `starters` or `addons` property:
* To generate a project based on {PRODUCT} process services using the `starters` property, enter the following command:
+
--
[source,subs="attributes+"]
----
$ mvn archetype:generate \
    -DarchetypeGroupId=org.kie.kogito \
    -DarchetypeArtifactId=kogito-springboot-archetype \
    -DgroupId=org.acme -DartifactId=sample-kogito \
    -DarchetypeVersion={COMMUNITY_VERSION_FINAL} \
    -Dversion=1.0-SNAPSHOT
    -Dstarters=processes
----
The new project includes the dependencies required to run {PRODUCT} process services. You can combine multiple {PRODUCT} Spring Boot starters using a comma-separated list. For example `starters=processes,rules`.
--

* To generate a project containing Prometheus monitoring and Infinispan persistence using the {PRODUCT} `add-ons` property, enter the following command:
+
--
[source,subs="attributes+"]
----
$ mvn archetype:generate \
    -DarchetypeGroupId=org.kie.kogito \
    -DarchetypeArtifactId=kogito-springboot-archetype \
    -DgroupId=org.acme -DartifactId=sample-kogito \
    -DarchetypeVersion={COMMUNITY_VERSION_FINAL} \
    -Dversion=1.0-SNAPSHOT
    -Dstarters=processes
    -Daddons=monitoring-prometheus,persistence-infinispan
----
////
Add a link of Kogito-add-ons section when prepared.
////

NOTE: When you pass an add-on to the property, the add-on name does not require the `kogito-addons-springboot` prefix. Also, you can combine the `add-ons` and `starters` properties to customize the project.
--

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

For more information about {PRODUCT} Spring Boot starters and {PRODUCT} add-ons, see xref:con-kogito-spring-boot-starters_kogito-creating-running[].

[id="proc-kogito-creating-project-custom_{context}"]
=== Creating a custom {PRODUCT} project using code scaffolding

WARNING: This feature is experimental and might be substantially modified or removed in a future release. This feature also requires a special project setup. The generated code uses APIs that are not final in {PRODUCT} and will not function the same way in future releases.

[role="_abstract"]
The Quarkus extension and Maven plug-in within a standard {PRODUCT} project generate all the required code and boilerplate for your {PRODUCT} services so that you do not have to write the project setup code yourself. By default, a {PRODUCT} project generates a REST service from business assets automatically. The generated service usually exposes default REST endpoints using the information that is inferred from the business assets that you include in your project.

If you want to customize the code for your {PRODUCT} project, such as adding more REST endpoints, you can use _code scaffolding_ to generate the project code to a specified user directory and then modify the code as needed.

With code scaffolding, you generate your {PRODUCT} project with the {PRODUCT} Maven archetype as usual, but you disable the project ability to automatically regenerate the project code and explicitly instruct {PRODUCT} to generate the code in a custom target directory. The code is generated one time in the specified target directory and is not regenerated at build time unless you explicitly request it. You can customize the project code in the specified target directory as needed.

NOTE: On Quarkus, disabling code regeneration also disables hot reload of business assets in development mode. This limitation will be improved in a future release.

.Procedure
. In a command terminal, navigate to a local folder where you want to store the custom {PRODUCT} project and enter the following command to generate your {PRODUCT} project with the {PRODUCT} Maven archetype as usual:
+
--
.On Quarkus
[source,subs="attributes+"]
----
$ mvn io.quarkus:quarkus-maven-plugin:create \
    -DprojectGroupId=org.acme -DprojectArtifactId=sample-kogito \
    -DprojectVersion=1.0.0-SNAPSHOT -Dextensions=kogito-quarkus
----

Alternatively, you can generate a project using the https://code.quarkus.io/?e=org.kie.kogito%3Akogito-quarkus[Quarkus website].

////
@comment: The following standard command for Quarkus isn't working currently but may be restored for Dev Preview

mvn io.quarkus:quarkus-maven-plugin:create -DprojectGroupId=com.company -DprojectArtifactId=sample-kogito -Dextensions="kogito"
////

.On Spring Boot
[source,subs="attributes+"]
----
$ mvn archetype:generate \
    -DarchetypeGroupId=org.kie.kogito \
    -DarchetypeArtifactId=kogito-spring-boot-archetype \
    -DgroupId=org.acme -DartifactId=sample-kogito \
    -DarchetypeVersion={COMMUNITY_VERSION_FINAL} \
    -Dversion=1.0-SNAPSHOT
----

This command generates a `sample-kogito` Maven project and imports the {PRODUCT} extension for all required dependencies and configurations to prepare your application for business automation.
--
. In the project `pom.xml` file, modify the project dependencies and plug-ins to disable code regeneration:
+
--
* *On Quarkus*: Delete the `kogito-quarkus` dependency and add the `kie-maven-plugin` plug-in, as shown in the following examples:
+
.Deleting the `kogito-quarkus` dependency
[source,xml]
----
<dependencies>
  ...
  <dependency>
    <groupId>org.jbpm</groupId>
    <artifactId>jbpm-quarkus</artifactId>
  </dependency>
  ...
</dependencies>
----
+
.Adding the `kie-maven-plugin` plug-in
[source,xml]
----
<build>
  ...
  <plugins>
    ...
    <plugin>
      <groupId>org.kie</groupId>
      <artifactId>kie-maven-plugin</artifactId>
      <configuration>
        <onDemand>true</onDemand>
      </configuration>
    </plugin>
    ...
  </plugins>
  ...
</build>
----

* *On Spring Boot*: Modify the existing `kie-maven-plugin` plug-in as shown in the following example:
+
.Modifying the `kie-maven-plugin` plug-in
[source,xml]
----
<build>
  ...
  <plugins>
    ...
    <plugin>
      <groupId>org.kie</groupId>
      <artifactId>kie-maven-plugin</artifactId>
      <configuration>
        <onDemand>true</onDemand>
      </configuration>
    </plugin>
    ...
  </plugins>
  ...
</build>
----
--
. In a command terminal, navigate to the root of your {PRODUCT} project and enter the following command to generate your modified project using code scaffolding:
+
--
.Generating the {PRODUCT} project using code scaffolding
[source]
----
 $ mvn compile kogito:scaffold
----

This command compiles the assets in your project and generates the code in the `src/main/java` directory. In the automatic {PRODUCT} project build, the default directory is `target/generated-sources/kogito`.

If you want to override the default location for code generation, use the following command to define a custom target directory:

.Generating the {PRODUCT} project using code scaffolding with a custom directory
[source]
----
 $ mvn compile kogito:scaffold -Dkogito.codegen.sources.directory=src/main/generated-java
----

The `kogito.codegen.sources.directory` parameter defines the custom target directory where you want the code to be generated, such as `src/main/generated-java` in this example.

WARNING: If you invoke the generation command again with the same target directory, the files are overwritten. This limitation will be fixed in a future release.

After you run the scaffolding command, either the default `src/main/java` directory or the custom target directory that you defined now contains the following resources:

* Your existing project files
* Generated data classes corresponding to process variables or Decision Model and Notation (DMN) definitions
* Generated REST endpoints

This example project contains a `persons` Business Process Model and Notation (BPMN) process model, so the generated REST endpoints are modified as shown in the following Java object:

.Modified REST endpoints for a `person` BPMN process model
[source,java]
----
package org.acme.travels;

// Imports

@Path("/persons")
@ApplicationScoped
public class PersonsResource {

    @Inject
    @Named("persons")
    Process<PersonsModel> process;

    @POST
    @Produces(MediaType.APPLICATION_JSON)
    @Consumes(MediaType.APPLICATION_JSON)
    public PersonsModelOutput createResource_persons(
            @Context HttpHeaders httpHeaders,
            @QueryParam("businessKey") String businessKey,
            @Valid @NotNull PersonsModelInput resource) {
        ...
    }

    // Other endpoints
}
----

The `PersonsModel`, `PersonsModelInput`, and `PersonsModelOutput` elements are the generated data models. These models are inferred automatically from the process variables in the process. Input and output models are inferred by how you tagged your process variables.

Similar endpoints are generated for any available rule units. This example project contains a `PersonValidationService` class for a rule unit model, so the generated REST endpoints are modified as shown in the following Java object:

.Modified REST endpoints for a `PersonValidationService` rule unit class
[source,java]
----
package org.acme.travels;

// Imports

@Path("/persons-validation-service")
@ApplicationScoped
public class PersonsValidationServiceResource {

    @Inject
    RuleUnit<PersonValidationService> unit;

    @POST
    @Produces(MediaType.APPLICATION_JSON)
    @Consumes(MediaType.APPLICATION_JSON)
    public QueryResult fireRules(PersonValidationService resource) {
        ...
    }

    // Other endpoints
}
----
--

[role="_additional-resources"]
.Additional resources
* {URL_PROCESS_SERVICES}#con-bpmn-variables_kogito-developing-process-services[Variables in {PRODUCT} processes]
* xref:proc-kogito-designing-app-rule-units_kogito-creating-running[]

[id="proc-kogito-custom-rest-endpoint-api_{context}"]
== Creating custom REST endpoints using {PRODUCT} API

{PRODUCT} enables you to create custom REST endpoints using {PRODUCT} API.

.Prerequisites
* JDK 17 is installed.
* Apache Maven is installed.

NOTE: The {PRODUCT} API is only available for Quarkus and is currently experimental. This feature is available to the adopters to collect feedback and modify in a future release.

.Procedure
. Create a {PRODUCT} project using the Maven plugin or Quarkus CLI.
+
--
.Example project using the Quarkus Maven plugin
[source,subs="attributes+"]
----
mvn io.quarkus:quarkus-maven-plugin:create \
   -DprojectGroupId=com.company \
   -DprojectArtifactId=sample-kogito \
   -Dextensions="kogito"
----
--

. Add a business asset to the `resource` folder such as a DMN file. To create the example DMN model, copy the following `PersonDecisions.dmn` file content:
+
--
[id="person-decisions-source-xml"]
.Example `PersonDecisions.dmn` file
[source,xml]
----
<?xml version="1.0" encoding="UTF-8" ?>
<dmn:definitions xmlns:dmn="https://www.omg.org/spec/DMN/20230324/MODEL/" xmlns="https://kie.org/dmn/_F322E39A-1EF2-470E-BD8C-960352D1EA36" xmlns:di="http://www.omg.org/spec/DMN/20180521/DI/" xmlns:kie="https://kie.org/dmn/extensions/1.0" xmlns:dmndi="https://www.omg.org/spec/DMN/20230324/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="https://www.omg.org/spec/DMN/20230324/FEEL/" namespace="https://kie.org/dmn/_F322E39A-1EF2-470E-BD8C-960352D1EA36">
  <dmn:parsererror style="display: block; white-space: pre; border: 2px solid #c77; padding: 0 1em 0 1em; margin: 1em; background-color: #fdd; color: black">
    <dmn:h3 />
    <dmn:h3 />
    <dmn:div style="font-family:monospace;font-size:12px" />
  </dmn:parsererror>
  <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 id="_E09E7797-14AA-4811-AA1E-61FFC737F4C6" name="Default DRD" useAlternativeInputDataShape="false">
      <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 id="_8B2F25AD-1B38-462A-9890-912D97103B9E">
          <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="320" y="200" width="100" height="50" />
        <dmndi:DMNLabel id="_97FE1357-957E-48C5-8222-BDD52128BE3A" />
      </dmndi:DMNShape>
      <dmndi:DMNShape id="dmnshape-_0D2BD7A9-ACA1-49BE-97AD-19699E0C9852" dmnElementRef="_0D2BD7A9-ACA1-49BE-97AD-19699E0C9852" isCollapsed="false">
        <dmndi:DMNStyle id="_8D4C2082-2C14-47DC-A872-E710845C9BBE">
          <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="580" y="200" width="100" height="50" />
        <dmndi:DMNLabel id="_B814BC45-74BA-4DB1-A3D6-EDCDB489856E" />
      </dmndi:DMNShape>
      <dmndi:DMNEdge id="dmnedge-_2F819B03-36B7-4DEB-AED6-2B46AE3ADB75" dmnElementRef="_2F819B03-36B7-4DEB-AED6-2B46AE3ADB75">
        <di:waypoint x="420" y="225" />
        <di:waypoint x="580" y="225" />
      </dmndi:DMNEdge>
    </dmndi:DMNDiagram>
  </dmndi:DMNDI>
</dmn:definitions>
----

The `PersonDecisions.dmn` file defines a DMN model with `https://kie.org/dmn/_F322E39A-1EF2-470E-BD8C-960352D1EA36` namespace and `PersonDecisions` name.
--

. Create a source file for the custom REST endpoint:
+
--
.Example REST endpoint
[source,java]
----
package org.acme;

import java.util.Map;

import javax.inject.Inject;
import javax.ws.rs.Consumes;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

import org.kie.kogito.incubation.application.AppRoot;
import org.kie.kogito.incubation.common.DataContext;
import org.kie.kogito.incubation.common.MapDataContext;
import org.kie.kogito.incubation.decisions.DecisionIds;
import org.kie.kogito.incubation.decisions.services.DecisionService;

@Path("/hello")
public class GreetingResource {

    // Inject the application root
    @Inject AppRoot appRoot;
    // Inject a decision service
    @Inject DecisionService svc;

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public DataContext hello(Map<String, Object> payload) {
        var id = appRoot
                .get(DecisionIds.class)
                .get("https://kie.org/dmn/_F322E39A-1EF2-470E-BD8C-960352D1EA36",
                        "PersonDecisions");
        var ctx = MapDataContext.from(payload);
        return svc.evaluate(id, ctx);
    }
}
----

The previous example of REST endpoints contains the following aspects:

* The `AppRoot` object is injected that is used to create identifiers for resources to be evaluated.
* The `@Inject DecisionService svc` injects the `DecisionService`, which is used to evaluate a DMN model. The following list describes different types of services:

** `StraightThroughProcessService` for BPMN processes that terminate immediately and do not suspend into intermediate states
** `DecisionService` for DMN decision models
** `PredictionService` for PMML predictive models
** `RuleUnitService` for Rule Unit evaluation
+
Each service can be injected (`@inject`) and provides an `evaluate(Id, DataContext)` method. For more information about how to invoke the services, you can see `dmn-incubation-api-quarkus`, `pmml-incubation-api-quarkus`, `process-incubation-api-quarkus`, and `rules-incubation-api-quarkus` example applications.

* The REST endpoint expects an arbitrary `Map<String, Object>` of values.
* In the body of the REST handler, the `Map` is converted into a `DataContext`. Each service expects a `DataContext` to evaluate together with the identifier.
* The `evaluate(id, ctx)` method returns a `DataContext`. The `DataContext` be returned directly by the REST handler: the system knows how to handle the response.

A `DataContext` is a class that implements the `DataContext` interface. `DataContext` provides  `<T extends DataContext> T as(Class<T>)` method to convert a type of data context to another. The root type of data context provides the `as()` method only, because the root type does not contain additional behavior.

In the previous example, `DataContext` is converted into a `MapDataContext` and `Person` object. The following is an example of using a `DataContext`:

.Example of using a `DataContext`
[source,java]
----
DataContext ctx = ...;
MapDataContext mctx = ctx.as(MapDataContext.class);
Person person = mctx.as(Person.class);
----

In the previous example, `MapDataContext` is a type of built-in data context (`Map<String, Object>`) and provides `get()` and `set()` methods to access the data. The `get()` method pulls the entered data by performing an internal conversion if applicable.

.Example of using `MapDataContext`
[source,java]
----
DataContext ctx = ...;
MapDataContext mctx = ctx.as(MapDataContext.class);
ctx.set("Paul", new Person("Paul", 79));
Object o = ctx.get("Paul");
Person p = ctx.get("Paul", Paul.class);
----

Also, you can customize the example REST endpoint further by expecting a `DataContext` in the method signature:

.Example REST endpoint
[source,java]
----
    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public DataContext hello(MapDataContext ctx) { // use ctx here
        var id = appRoot
                .get(DecisionIds.class)
                .get("https://kiegroup.org/dmn/rest-example",
                        "PersonDecisions");
        return svc.evaluate(id, ctx);
    }
----

In addition, you can transform the Map data context into a Java class. This mapping is performed automatically using field naming conventions as shown in the following example:

.Example Java class
[source,java]
----
import org.kie.kogito.incubation.common.*;
public class Person implements DataContext, DefaultCastable {
    String name;
    int age;
    // constructors...
    // getters and setters...
}
----

The `DataContext` interface marks the Java class as a bindable context, enabling you to convert another `DataContext` using the `as(Class<DataContext>)` method:

.Example conversion of a `MapDataContext` into a `Person`
[source,java]
----
    public DataContext hello(MapDataContext ctx) {
        ...
        Person person = ctx.as(Person.class);
        return svc.evaluate(id, person);
    }
----

Also, you can use the converted `DataContext` directly as an argument. In the following example, the `Person` is used as an argument:

.Example REST endpoint using `Person` as an argument
[source,java]
----
    public DataContext hello(Person person) {
        ...
        return svc.evaluate(id, ctx);
    }
----

The custom data contexts can also be used in the return type as shown in the following example:

.Example REST endpoint using `Person` as an argument and a custom return type
[source,java]
----
    class MyCustomDataContext implements DataContext, DefaultCastable {...}
    public MyCustomDataContext hello(Person person) {
        ...
        DataContext result = svc.evaluate(id, ctx);
        MyCustomDataContext typedResult = result.as(MyCustomDataContext.class)
        return result;
    }
----
--

. Optionally, you can disable automated generation of the REST endpoint by setting `kogito.generate.rest.decisions` property to `false` in the `application.properties` file:
+
--
.`application.properties` file
[source,subs="attributes+"]
----
kogito.generate.rest.decisions=false
----
--

. Test the created custom REST endpoint:
+
--
.Example of invoking a REST endpoint
[source,subs="attributes+"]
----
# starts the application in devmode
$ mvn quarkus:dev
# invoke the REST service
$ curl -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name": "Paul" , "age" : 79}' \
    http://localhost:8080/hello
----

.Example response
[source,json,subs="attributes+"]
----
{
  "name":"Paul",
  "adult":true,
  "age":79
}
----
--

[id="con-kogito-spring-boot-starters_{context}"]
== Spring Boot Starters for your {PRODUCT} project

The https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#using-boot-starter[Spring Boot starters] are a set of dependency descriptors that you can include in your {PRODUCT} application. Using Spring Boot starters, you can eliminate the need to go through sample code, and copy and pasting dependency descriptors.

When you create a project, the `pom.xml` file contains all the necessary starters. You can also include a new starter if required. For more information on creating projects using {PRODUCT} Spring Boot archetype, see xref:proc-customizing-spring-boot-project-creation_kogito-creating-running[].

[id="ref-kogito-spring-boot-starter_{context}"]
=== {PRODUCT} Spring Boot Starters

The {PRODUCT} Spring Boot starter is an all-in-one descriptor for the {PRODUCT} projects that require business automation engines provided by {PRODUCT}. The {PRODUCT} Spring Boot starter includes decisions, rules, processes, predictions, and the Serverless Workflow implementation.

When your project consists of all the assets and you want a quick way to get started with {PRODUCT}, you can use the `kogito-spring-boot-starter`. For more granular approach, you can use the specific starters or a combination of starters.

You can add a {PRODUCT} Spring Boot starter to your project as follows:

[source,xml]
----
<dependencies>
  <dependency>
    <groupId>org.jbpm</groupId>
    <artifactId>jbpm-spring-boot-starter</artifactId>
  </dependency>
</dependencies>
----

The following list describes the different Spring Boot starters:

{PRODUCT} decisions Spring Boot starter::
Starter for decisions such as DMN support for your {PRODUCT} Spring Boot project. You can add a {PRODUCT} decisions Spring Boot starter as follows:

[source,xml]
----
<dependencies>
  <dependency>
    <groupId>org.drools</groupId>
    <artifactId>drools-rules-spring-boot-starter</artifactId>
  </dependency>
</dependencies>
----
{PRODUCT} predictions Spring Boot starter::
Starter for predictions such as PMML support for your {PRODUCT} Spring Boot project. You can add a {PRODUCT} predictions Spring Boot starter as follows:

[source,xml]
----
<dependencies>
  <dependency>
    <groupId>org.kie</groupId>
    <artifactId>kie-predictions-spring-boot-starter</artifactId>
  </dependency>
</dependencies>
----

{PRODUCT} processes Spring Boot starter::
Starter for processes such as BPMN support for your {PRODUCT} Spring Boot project. You can add a {PRODUCT} processes Spring Boot starter as follows:

[source,xml]
----
<dependencies>
  <dependency>
    <groupId>org.jbpm</groupId>
    <artifactId>jbpm-with-drools-spring-boot-starter</artifactId>
  </dependency>
</dependencies>
----

{PRODUCT} rules Spring Boot starter::
Starter for rules such as DRL support for your {PRODUCT} Spring Boot project. You can add a {PRODUCT} rules Spring Boot starter as follows:

[source,xml]
----
<dependencies>
  <dependency>
    <groupId>org.drools</groupId>
    <artifactId>drools-rules-spring-boot-starter</artifactId>
  </dependency>
</dependencies>
----

// Add-Ons

[id="ref-kogito-add-ons_{context}"]
== {PRODUCT} add-ons

[role="_abstract"]
You can extend {PRODUCT} core capabilities by using add-ons modules. The add-on modules extend persistence, monitoring, messaging, and other features of {PRODUCT} services.

The following tables list all the supported add-ons:

.{PRODUCT} add-ons for Quarkus
[cols="20%,50%,20%"]
|===
|Name                     |Artifact Id                                          |Since

|Messaging                | kie-addons-quarkus-messaging                     |1.0.0
|Events Decisions         | kie-addons-quarkus-events-decisions              |1.2.0
|Events Process           | kie-addons-quarkus-events-process                |0.3.0
|Explainability           | kie-addons-quarkus-explainability                |0.15.0
|Jobs Management          | kie-addons-quarkus-jobs-management               |0.6.0
|Knative Eventing         | kie-addons-quarkus-knative-eventing              |1.10.0
|Mail                     | jbpm-addons-quarkus-mail                          |1.6.0
|Elastic Monitoring       | kie-addons-quarkus-monitoring-elastic            |1.2.0
|Prometheus Monitoring    | kie-addons-quarkus-monitoring-prometheus         |0.1.0
|Persistence ISPN Health  | kie-addons-quarkus-persistence-infinispan-health |0.8.0
|Persistence Kafka        | kie-addons-quarkus-persistence-kafka             |1.4.0
|Process Management       | kie-addons-quarkus-process-management            |0.3.0
|Process SVG              | kie-addons-quarkus-process-svg                   |1.0.0
|Task Management          | jbpm-addons-quarkus-task-management               |1.4.0
|Task Notification        | kogito-addons-quarkus-task-notification             |1.6.0
|Tracing Decision         | kie-addons-quarkus-tracing-decision              |0.11.0
|Events MongoDB           | kie-addons-quarkus-events-mongodb                |1.11.0
|Source Files             | kie-addons-quarkus-source-files                  |1.20.0
|===

.{PRODUCT} add-ons for Spring Boot
[cols="20%,50%,20%"]
|===
|Name                 |Artifact Id                                    |Since

|Messaging            |kie-addons-springboot-messaging             |1.0.0
|Events Decisions     |kie-addons-springboot-events-decisions      |1.2.0
|Events Kafka         |kie-addons-springboot-events-process-kafka          |0.3.0
|Explainability       |kie-addons-springboot-explainability        |0.15.0
|Jobs Management      |kie-addons-springboot-jobs-management       |0.6.0
|Mail                 |jbpm-addons-springboot-mail                  |1.6.0
|Elastic Monitoring   |kie-addons-springboot-monitoring-elastic    |1.2.0
|Prometheus Monitoring|kie-addons-springboot-monitoring-prometheus |0.1.0
|Process Management   |kogito-addons-springboot-process-management    |0.3.0
|Process SVG          |kie-addons-springboot-process-svg           |1.0.0
|Task Management      |jbpm-addons-springboot-task-management       |1.4.0
|Task Notification    |kogito-addons-springboot-task-notification     |1.6.0
|Tracing Decision     |kie-addons-springboot-tracing-decision      |0.11.0
|Events MongoDB       |kie-addons-springboot-events-mongodb        |1.11.0

|===


=== {PRODUCT} messaging add-on

{PRODUCT} provides a messaging add-on, enabling a process to register an event listener. The messaging add-on uses events in the {PRODUCT} projects. For more information, see the following sections:

* xref:con-kogito-runtime-events_kogito-configuring[{PRODUCT} runtime events]
* xref:con-kogito-travel-agency_kogito-deploying-on-openshift[Travel agency tutorial for {PRODUCT} services on OpenShift]
* xref:con-data-index-service_kogito-configuring[{PRODUCT} Data Index Service]
* xref:con-trusty-service_kogito-configuring[{PRODUCT} Trusty Service and Explainability Service]

To configure messaging capabilities for your Kogito services, you must add the messaging add-on as a dependency in the `pom.xml` file of your Kogito project:

.Project dependency to enable messaging operations in Quarkus projects
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-messaging</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Project dependency to enable messaging operations in Spring Boot projects
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-springboot-messaging</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

For Quarkus, the {PRODUCT} process event add-on implementation is based on https://smallrye.io/smallrye-reactive-messaging/smallrye-reactive-messaging/2/connectors/connectors.html[Smallrye Messaging] library, which provides a set of connectors for event brokers, such as JMS, AMQP, and Kafka. Therefore, the {PRODUCT} process event add-on is not specifically combined with any event broker, but also requires additional configuration to use a suitable Smallrye connector.

For example, to use Kafka as an event broker in Quarkus, you must add the following dependency in the `pom.xml` file of your {PRODUCT} project:

.Project dependency to enable event broker in Quarkus
[source,xml,subs="attributes+"]
----
<dependency>
   <groupId>io.quarkus</groupId>
   <artifactId>quarkus-smallrye-reactive-messaging-kafka</artifactId>
</dependency>
----

Smallrye uses an abstraction named `channel`. The implementation of channels depends on the underlying event broker. For example, when using Kafka, every channel is mapped to a topic. 

Channels are configured by using properties. The pattern for these properties is `mp.messaging.[incoming|outgoing].<channel name>.<property_name>`.

{PRODUCT} allows different channel mapping strategies:

* Define one default incoming channel to receive all the incoming messages and one default outgoing channel to store all the published messages.
* Define a channel for each message name so that every message type has a dedicated channel.
* Define a channel for certain message names and let the not mapped message names to use the default incoming or outgoing channel. 

{PRODUCT} first searches for channel name equals to message name in the properties. If found, it uses that channel for that message name. If not, it searches for default channel definition. If also not existing, then an error will be reported. 

The name for the default incoming channel is `kogito_incoming_stream` and for the default outgoing channel is `kogito_outgoing_stream`. 

You can change the default incoming and outgoing topic name as follows:

.Quarkus
[source]
----
kogito.addon.messaging.incoming.defaultName=<default channel name>
kogito.addon.messaging.outgoing.defaultName=<default channel name>
----

.Spring Boot
[source]
----
kogito.addon.cloudevents.kafka.kogito_incoming_stream=<default channel name>
kogito.addon.cloudevents.kafka.kogito_outgoing_stream=<default channel name>
----

Optionally, for Kafka connector, you can define the Kafka topic to be used for that channel using the following form:

`mp.messaging.[incoming|outgoing].<channel name>.topic = <topic name>`

If the topic property is not found, then the topic name is considered to be the same as Kafka name. Note that you can map different channels to the same topic, if you wish to do so. 

==== Providing a key for a Kafka record

To specify the key to your Kafka record, you can use a custom https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/quarkus/addons/messaging/common/src/main/java/org/kie/kogito/addon/quarkus/messaging/common/message/MessageDecorator.java[MessageDecorator] implementation. 

For an example, see https://github.com/apache/incubator-kie-kogito-examples/blob/main/kogito-quarkus-examples/process-kafka-avro-multi-quarkus/src/main/java/org/acme/travel/StringKeyDecorator.java[StringKeyDecorator.java]

==== Customizing message format

By default, {PRODUCT} uses Cloud event JSON format for messaging. However, you can change the default format by providing your own https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/api/kogito-events-api/src/main/java/org/kie/kogito/event/EventMarshaller.java[event marshaler] implementation. 
For an example, see https://github.com/apache/incubator-kie-kogito-examples/blob/main/kogito-quarkus-examples/process-kafka-avro-multi-quarkus/src/main/java/org/acme/travel/AvroEventMarshaller.java[AvroEventMarshaller.java example] 


=== {PRODUCT} Decision Model and Notation (DMN) event-driven add-on

.Quarkus
To use the DMN event-driven add-on, add the following code to the `pom.xml` file of your project:
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-events-decisions</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Spring Boot
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-springboot-events-decisions</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

=== {PRODUCT} explainability add-on

The Explainability add-on in {PRODUCT} provides integration with Explainability and Trusty Services.

For more information, see the xref:con-trusty-service_kogito-configuring[].

To use the explainability add-on, add the following code to the `pom.xml` file of your project:

.Quarkus
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-explainability</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Spring Boot
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-springboot-explainability</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

=== {PRODUCT} jobs management add-on

The Jobs Management add-on provides integration and configuration for a project using the supporting services related to Jobs. For more information, see the xref:con-jobs-service_kogito-configuring[documentation].

To use the Jobs Management add-on, add the following code to the `pom.xml` file of your project:

.Quarkus
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-jobs-management</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Spring Boot
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-springboot-jobs-management</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

=== {PRODUCT} Knative Eventing add-on

The Knative Eventing add-on is used in the {PRODUCT} project for messaging. The https://github.com/apache/incubator-kie-kogito-runtimes/tree/main/addons/common/knative/eventing[{PRODUCT} Knative Eventing] add-on enables your project to connect to a https://knative.dev/docs/developer/eventing/sinks/[sink] or make it a https://github.com/knative-sandbox/eventing-kogito#kogito-source[KogitoSource].

The add-on processes the https://knative.dev/development/developer/eventing/sources/sinkbinding/[`K_SINK`] and https://knative.dev/development/developer/eventing/sources/sinkbinding/reference/#cloudevent-overrides[`K_CE_OVERRIDES`] environment variables injected by Knative Eventing controllers (`SinkBinding` or `KogitoSource`).

The service requires the https://github.com/apache/incubator-kie-kogito-runtimes/tree/main/addons/common/messaging[{PRODUCT} Messaging] and https://quarkus.io/guides/reactive-messaging-http.html[Quarkus HTTP connector] libraries to wire the {PRODUCT} service with a given sink. The {PRODUCT} Messaging and Quarkus HTTP connector perform as dependencies for the Knative Eventing add-on.

NOTE: Spring Boot does not support Knative Eventing currently.

For more information, see xref:con-knative-eventing_kogito-developing-process-services[].

To use the Knative Eventing add-on, add the following code to the `pom.xml` file of your project:

.Quarkus
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-knative-eventing</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

==== Auto-generated Knative resources

The Knative Eventing add-on can generate Knative Eventing resources by inspecting your BPMN or Serverless Workflow files for event definitions. For more information about creating BPMN files using message trigger events, see {URL_PROCESS_SERVICES}#con-knative-eventing_kogito-developing-process-services[_Knative Eventing in {PRODUCT} services_]. You can also see {URL_ORCHESTRATING_SERVICES}#chap-kogito-orchestrating-serverless[_{ORCHESTRATING_SERVICES}_] to know more about the Serverless Workflow events.

To enable the auto-generation of Knative resources, add the following dependency to your project:

[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-kubernetes</artifactId>
</dependency>
----

After adding the previous dependency, the add-on generates Knative Eventing resources to handle the events that are produced or consumed by your BPMN or Serverless Workflow resources on Knative Eventing platform.

For each consumed event, the add-on generates a https://knative.dev/docs/eventing/broker/triggers/[Knative Eventing Trigger] as shown in the following example:

.Example Knative `Trigger` custom resource for a {PRODUCT} service with `Broker` binding
[source,yaml]
----
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: travellers-trigger-process-knative-quickstart-quarkus
spec:
  broker: default
  filter:
    attributes:
      type: travellers
  subscriber:
    ref:
      apiVersion: serving.knative.dev/v1
      kind: Service
      name: process-knative-quickstart-quarkus
----

The `Trigger` resource requires a subscriber to receive the events that are routed by the `Broker`. In this case, the current {PRODUCT} service work as a subscriber, and the Knative Eventing add-on uses the {PRODUCT} service deployment, which is configured by Quarkus Kubernetes.

If a `Broker` is not specified, the Knative Eventing add-on generates a default `InMemoryChannel` as follows:

.Example `Broker` custom resource for Knative Eventing with default `InMemoryChannel`
[source,yaml]
----
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
  name: default
----

If a `Broker` is configured in the target namespace, you can specify the `Broker` using the following property:
`org.kie.kogito.addons.knative.eventing.broker=myKafkaBroker`.

If the {PRODUCT} service contains any produced event definitions, the Knative Eventing add-on generates a https://knative.dev/development/eventing/custom-event-source/sinkbinding/[Knative Eventing `SinkBinding`], or a https://github.com/knative-sandbox/eventing-kogito#kogito-source[Knative Eventing `KogitoSource`]. By default, the `SinkBinding` is generated, but you can change this behavior by setting `org.kie.kogito.addons.knative.eventing.generate-kogito-source` property to `true`.

.Example `SinkBinding` custom resource for Knative Eventing
[source,yaml]
----
apiVersion: sources.knative.dev/v1
kind: SinkBinding
metadata:
  name: sb-process-knative-quickstart-quarkus
spec:
  sink:
    ref:
      apiVersion: eventing.knative.dev/v1
      kind: Broker
      name: default
  subject:
    apiVersion: serving.knative.dev/v1
    kind: Service
    name: process-knative-quickstart-quarkus
----

.Example `KogitoSource` custom resource for Knative Eventing
[source,yaml]
----
apiVersion: kogito.knative.dev/v1alpha1
kind: KogitoSource
metadata:
  name: process-knative-quickstart-quarkus
spec:
  sink:
    ref:
      apiVersion: eventing.knative.dev/v1
      kind: Broker
      name: default
      namespace: ""
  subject:
    apiVersion: serving.knative.dev/v1
    kind: Service
    name: process-knative-quickstart-quarkus
----

The target deployment defined in the Quarkus Kubernetes plugin work as the subject for `SinkBinding` and `KogitoSource`. You can configure the `sink` using the application properties. By default, the generated `Broker` is defined as the `sink`.

The following table lists all the available properties for the Knative Eventing add-on:

.{PRODUCT} Knative Eventing Add-on  properties
[cols="50%,20%,20%", options="header"]
|===
|Property
|Description
|Example value

|`org.kie.kogito.addons.knative.eventing.sink.namespace`
|Property for set sink namespace
|`default`

|`org.kie.kogito.addons.knative.eventing.sink.name`
|Property to set sink name
|`my-sink`

|`org.kie.kogito.addons.knative.eventing.sink.api-version`
|Property to set Kubernetes API version of the sink
|`eventing.knative.dev/v1`

|`org.kie.kogito.addons.knative.eventing.sink.kind`
|Property to set Kubernetes resource kind of the sink
|`Broker`

|`org.kie.kogito.addons.knative.eventing.broker`
|Property to set name of the pre-defined Broker
|`myKafkaBroker`

|`org.kie.kogito.addons.knative.eventing.generate-kogito-source`
|Property to enable the generation of `KogitoSource` instead of `SinkBinding`
|`false`

|`org.kie.kogito.addons.knative.eventing.auto-generate-broker`
|Property to enable the generation of default in-memory Broker
|`true`
|===

For more information about the Knative Eventing add-on, see the following example applications:

* https://github.com/apache/incubator-kie-kogito-examples/tree/main/kogito-quarkus-examples/process-knative-quickstart-quarkus[Process Knative Eventing]

=== {PRODUCT} mail add-on

The mail add-on is used to send emails in a process project. To use the mail add-on, add the following code to the `pom.xml` file of your project:

.Quarkus
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.jbpm</groupId>
  <artifactId>jbpm-addons-quarkus-mail</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Spring Boot
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.jbpm</groupId>
  <artifactId>jbpm-addons-springboot-mail</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

=== {PRODUCT} events add-on

The events add-on provides a default implementation in supported target platforms for EventEmitter and EventReceiver interfaces. You can use EventEmitter and EventReceiver interfaces to enable messaging by process, serverless workflow events, and event decision handling. For more information, see xref:con-knative-eventing_kogito-developing-process-services[], xref:proc-messaging-enabling_kogito-configuring[].

==== Implementing message payload decorator
Any dependant add-on can implement the https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/messaging/common/src/main/java/org/kie/kogito/addon/cloudevents/message/MessagePayloadDecorator.java[MessagePayloadDecorator].

.Prerequisites

* You have installed the Events add-on in {PRODUCT}.

.Procedure
. Create a file named `META-INF/services/org.kie.kogito.add-on.cloudevents.message.MessagePayloadDecorator` in your class path.
. Open the file.
. Enter the full name of your implementation class in the file.
. Save the file.

The `MessagePayloadDecoratorProvider` loads the file upon application startup and adds the file to the decoration chain. When {PRODUCT} calls the https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/messaging/common/src/main/java/org/kie/kogito/addon/cloudevents/message/MessagePayloadDecoratorProvider.java[MessagePayloadDecoratorProvider#decorate], your implementation is part of the decoration algorithm.

To use the events add-on, add the following code to the `pom.xml` file of your project:

.Events smallrye add-on for Quarkus
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-events-process</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Events decisions add-on for Quarkus
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-events-decisions</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Events Kafka add-on for Spring Boot
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-springboot-events-process-kafka</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Events decisions add-on for Spring Boot
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-springboot-events-decisions</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

=== {PRODUCT} monitoring add-on

The monitoring add-on provides monitoring capabilities in the {PRODUCT} project. For more information, see xref:_metrics_monitoring_in_kogito_services[Metrics monitoring in {PRODUCT}].

To use the monitoring add-on, add the following code to the `pom.xml` file of your project:

.Quarkus dependency for elastic search
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-monitoring-elastic</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Quarkus dependency for Prometheus
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-monitoring-prometheus</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Spring Boot dependency for elastic search
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-springboot-monitoring-elastic</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Spring Boot dependency for Prometheus
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-springboot-monitoring-prometheus</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

=== {PRODUCT} persistence add-on

The persistence add-on provides persistence capability in your {PRODUCT} project. For more information, xref:con-persistence_kogito-developing-process-services[].

To use the Persistence add-on, add the following code to the `pom.xml` file of your project:

.Quarkus dependency for persistence filesystem
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-persistence-filesystem</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Spring Boot dependency for persistence filesystem
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-springboot-persistence-filesystem</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Quarkus dependency for persistence Infinispan
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-persistence-infinispan</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Spring Boot dependency for persistence Infinispan
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-springboot-persistence-infinispan</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Quarkus dependency for persistence JDBC
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-persistence-jdbc</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Spring Boot dependency for persistence JDBC
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-springboot-persistence-jdbc</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Quarkus dependency for persistence MongoDB
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-persistence-mongodb</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Spring Boot dependency for persistence MongoDB
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-springboot-persistence-mongodb</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Quarkus dependency for persistence PostgreSQL
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-persistence-postgresql</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Spring Boot dependency for persistence PostgreSQL
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kogito-addons-springboot-persistence-postgresql</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Quarkus dependency for persistence Kafka
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-persistence-kafka</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----


include::{asciidoc-dir}/bpmn/chap-kogito-developing-process-services.adoc[tags=con-bpmn-process-management-addon,leveloffset=+1]
include::{asciidoc-dir}/bpmn/chap-kogito-developing-process-services.adoc[tags=con-bpmn-process-svg-addon,leveloffset=+1]
include::{asciidoc-dir}/bpmn/chap-kogito-developing-process-services.adoc[tags=con-bpmn-process-event-addon,leveloffset=+1]

=== {PRODUCT} task management add-on

The Task Management add-on provides integration with the https://github.com/apache/incubator-kie-kogito-apps/tree/master/task-console[Task Console]. For more information, see xref:con-task-console_kogito-developing-process-services[{PRODUCT} Task Console].

To use the Task Management add-on, add the following code to the `pom.xml` file of your project:

.Quarkus
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.jbpm</groupId>
  <artifactId>jbpm-addons-quarkus-task-management</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Spring Boot
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.jbpm</groupId>
  <artifactId>jbpm-addons-springboot-task-management</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

=== {PRODUCT} tracing add-on

The Tracing add-on provides Decision model and notation (DMN) services tracing capability. For more information, see the https://docs.jboss.org/kogito/release/latest/html_single/#con-trusty-service_kogito-configuring [documentation].

To use the Tracing add-on, add the following code to the `pom.xml` file of your project:

.Quarkus
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-tracing-decision</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

.Spring boot
[source,xml,subs="attributes+"]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-springboot-tracing-decision</artifactId>
  <version>{PRODUCT_VERSION}</version>
</dependency>
----

[#source-files-add-on]
=== {PRODUCT} source files add-on

The {PRODUCT} Source Files Add-on adds the capability of listing and downloading source files to {PRODUCT} projects.

> **⚠️**
This add-on isn't supposed to be used by end-users, if not needed for internal integrations, since it can be a potential security breach for some users' use cases.

To add the endpoints to download your services' source files, you can add the source files add-on as a dependency in your `pom.xml` file.

.Project dependency to enable source files endpoints
[source,xml]
----
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-source-files</artifactId>
</dependency>
----

Access to all the endpoints is granted to the role `source-files-client`.
To define basic authentication, you can add the following code to your `application.properties` file:

.Example of credentials for the user `scott` and password `jb0ss`
[source,properties]
----
quarkus.security.users.embedded.enabled=true
quarkus.security.users.embedded.plain-text=true
quarkus.security.users.embedded.users.scott=jb0ss
quarkus.security.users.embedded.roles.scott=source-files-client
----

You can also disable plain-text passwords by setting the `quarkus.security.users.embedded.plain-text` property to
`false` or just removing it from the configuration. In this case, the passwords are encrypted using MD5.

.Example of credentials for the user `scott` and password `jb0ss` encrypted using MD5
[source,properties]
----
quarkus.security.users.embedded.enabled=true
quarkus.security.users.embedded.users.scott=4960d03c13b5aff4ca6886758a8be019
quarkus.security.users.embedded.roles.scott=source-files-client
----

To define a more robust authentication mechanism, you can refer to the https://quarkus.io/guides/security[Quarkus documentation].

The Source Files Add-on provides REST support for the following operation:

==== List all the source files for the specified process

* GET: `/management/processes/{processId}/sources`
** parameters:
*** processId: process identifier
** output:
*** JSON with related source files URIs

.Example: to list the source files for the process with id `petstore_http`, you can use the following command:

[source,bash]
----
$ curl -X 'GET' \
  'http://localhost:8080/management/processes/petstore_http/sources' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic c2NvdHQ6amIwc3M='
----

.Output

[source,json]
----
[
  {
    "uri": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/json/petstore-simple.json"
  },
  {
    "uri": "/sources/org/kie/kogito/examples/petstore_http.sw.json"
  }
]
----

==== Download the specified source file

* GET: `/management/processes/{processId}/source`
** parameters:
*** processId: process identifier
** output:
*** Source file content used by the editor

.Example: to list the source file for the process with id `petstore_http`, you can use the following command:

[source,bash]
----
$ curl -X 'GET' \
  'http://localhost:8080/management/processes/petstore_http/source' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic c2NvdHQ6amIwc3M='
----

.Output

[source,json]
----
{
  "id": "petstore_http",
  "version": "1.0",
  "name": "Send CloudEvent after creating Pluto",
  "start": "AddPluto",
  "functions": [
    {
      "name": "addPet",
      "operation": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/json/petstore-simple.json#addPet"
    }
  ],
  "states": [
    {
      "name": "AddPluto",
      "type": "operation",
      "actions": [
        {
          "functionRef": {
            "refName": "addPet",
            "parameters": {
              "body": {
                "name": "Pluto"
              }
            }
          }
        }
      ],
      "end": true
    }
  ]
}
----
.Example: to download the source file located at `org/kie/kogito/examples/petstore_http.sw.json`, you can use the following command:

[source,bash]
----
$ curl -X 'GET' \
  'http://localhost:8080/sources?uri=org/kie/kogito/examples/petstore_http.sw.json' \
  -H 'accept: */*' \
  -H 'Authorization: Basic c2NvdHQ6amIwc3M='
----

[id="proc-kogito-designing-app_{context}"]
== Designing the application logic for a {PRODUCT} service using DMN and BPMN

[role="_abstract"]
After you create your {PRODUCT} project, you can create or import Business Process Model and Notation (BPMN) 2.0 business processes, Decision Model and Notation (DMN) decision models, Drools Rule Language (DRL) business rules, XLS or XLSX decision tables, and other assets 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 business processes or decisions.

The example for this procedure is a basic {PRODUCT} service that provides a REST endpoint `/persons`. This endpoint is automatically generated based on an example `PersonProcess.bpmn2` business process that employs an example `PersonDecisions.dmn` DMN model to make decisions based on the data being processed.

The business process contains the business logic of the {PRODUCT} service. The process provides the complete set of steps to achieve the business goal. The process is also the entry point to the service that can be consumed by other services.

The business decision contains the decision logic of the {PRODUCT} service. In this example, the decision logic is invoked as part of the business process. You can define business rules and decisions in several ways, such as with DMN models, DRL rules, or XLS or XLSX decision tables. The example for this procedure uses a DMN model.

.Procedure
. In the Maven project that you generated for your {PRODUCT} service, navigate to the `src/main/java/org/acme` folder and add the following `Person.java` file:
+
--
.Example person Java object
[source,java]
----
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.
--
. Navigate to the `src/main/resources` folder and add the following `PersonDecisions.dmn` DMN decision model:
+
--
.Example `PersonDecisions` DMN decision requirements diagram (DRD)
image::kogito/creating-running/kogito-dmn-example-person.png[Image of PersonDecisions decision diagram]

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 (recommended), you can add the *{VSCODE_EXTENSION}* VSCode extension to design the decision requirements diagram (DRD), boxed expression, and data types with the {PRODUCT} DMN modeler.

To create this example DMN model quickly, you can copy <<person-decisions-source-xml>>.

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

.. Open the empty `PersonDecisions.dmn` file and in the upper-right corner of the DMN modeler, click the *Properties* icon and confirm that the DMN model *Name* is set to `PersonDecisions`.
.. In the left palette, select *DMN Input Data*, drag the node to the canvas, and double-click the node to name it `Person`.
.. In the left palette, select *DMN Decision*, drag the node to the canvas, double-click the node to name it `isAdult`, and link to it from the input node.
.. 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.
.. Click the undefined expression field and select *Decision Table*.
.. Click the upper-left corner of the decision table to set the hit policy to *Unique*.
.. 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:
+
.Example DMN decision table for `isAdult` decision
image::kogito/creating-running/kogito-dmn-example-person-logic.png[Image of PersonDecisions decision table]
.. In the upper tab options, select the *Data Types* tab and add the following `tPerson` structured data type and nested data types:
+
.Example DMN data types
image::kogito/creating-running/kogito-dmn-example-person-data-types.png[Image of PersonDecisions data types]
.. After you define the data types, select the *Editor* tab to return to the DMN modeler canvas.
.. Select the *Person* input node, click the *Properties* icon, and under *Information item*, set the *Data type* to `tPerson`.
.. 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.
.. Save the DMN decision file.
--
. In the `src/main/resources` folder, add the following `PersonProcess.bpmn2` BPMN process model:
+
--
.Example `PersonProcess` BPMN process
image::kogito/creating-running/kogito-bpmn-example-person.png[Image of person process diagram]

This example process consists of the following basic BPMN components:

* Start event
* Business rule task
* Exclusive gateway
* User task
* End events

In VSCode (recommended), you can add the *{VSCODE_EXTENSION}* VSCode extension to model the business process with the {PRODUCT} BPMN modeler.

To create this example process quickly, you can copy the following `PersonProcess.bpmn2` file content:

.Example BPMN file
[source,xml]
----
<bpmn2:definitions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bpmn2="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:bpsim="http://www.bpsim.org/schemas/1.0" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:drools="http://www.jboss.org/drools" id="_J4ElsVJgEDiScotxwBQ14Q" exporter="jBPM Process Modeler" exporterVersion="2.0" targetNamespace="http://www.omg.org/bpmn20">
  <bpmn2:itemDefinition id="_personItem" structureRef="org.acme.Person"/>
  <bpmn2:itemDefinition id="_isAdultItem" structureRef="Boolean"/>
  <bpmn2:itemDefinition id="_UserTask_1_SkippableInputXItem" structureRef="Object"/>
  <bpmn2:itemDefinition id="_UserTask_1_PriorityInputXItem" structureRef="Object"/>
  <bpmn2:itemDefinition id="_UserTask_1_CommentInputXItem" structureRef="Object"/>
  <bpmn2:itemDefinition id="_UserTask_1_DescriptionInputXItem" structureRef="Object"/>
  <bpmn2:itemDefinition id="_UserTask_1_CreatedByInputXItem" structureRef="Object"/>
  <bpmn2:itemDefinition id="_UserTask_1_TaskNameInputXItem" structureRef="Object"/>
  <bpmn2:itemDefinition id="_UserTask_1_GroupIdInputXItem" structureRef="Object"/>
  <bpmn2:itemDefinition id="_UserTask_1_ContentInputXItem" structureRef="Object"/>
  <bpmn2:itemDefinition id="_UserTask_1_NotStartedReassignInputXItem" structureRef="Object"/>
  <bpmn2:itemDefinition id="_UserTask_1_NotCompletedReassignInputXItem" structureRef="Object"/>
  <bpmn2:itemDefinition id="_UserTask_1_NotStartedNotifyInputXItem" structureRef="Object"/>
  <bpmn2:itemDefinition id="_UserTask_1_NotCompletedNotifyInputXItem" structureRef="Object"/>
  <bpmn2:itemDefinition id="_UserTask_1_personInputXItem" structureRef="org.acme.Person"/>
  <bpmn2:itemDefinition id="_BusinessRuleTask_1_namespaceInputXItem" structureRef="java.lang.String"/>
  <bpmn2:itemDefinition id="_BusinessRuleTask_1_modelInputXItem" structureRef="java.lang.String"/>
  <bpmn2:itemDefinition id="_BusinessRuleTask_1_decisionInputXItem" structureRef="java.lang.String"/>
  <bpmn2:itemDefinition id="_BusinessRuleTask_1_PersonInputXItem" structureRef="org.acme.Person"/>
  <bpmn2:itemDefinition id="_BusinessRuleTask_1_isAdultOutputXItem" structureRef="Boolean"/>
  <bpmn2:process id="persons" drools:packageName="org.acme" drools:version="1.0" drools:adHoc="false" name="Person Process" isExecutable="true" processType="Public">
    <bpmn2:property id="person" itemSubjectRef="_personItem" name="person"/>
    <bpmn2:property id="isAdult" itemSubjectRef="_isAdultItem" name="isAdult"/>
    <bpmn2:sequenceFlow id="SequenceFlow_1" sourceRef="StartEvent_1" targetRef="BusinessRuleTask_1"/>
    <bpmn2:sequenceFlow id="SequenceFlow_2" sourceRef="BusinessRuleTask_1" targetRef="ExclusiveGateway_1"/>
    <bpmn2:sequenceFlow id="SequenceFlow_3" sourceRef="ExclusiveGateway_1" targetRef="UserTask_1">
      <bpmn2:conditionExpression xsi:type="bpmn2:tFormalExpression" language="http://www.java.com/java">return isAdult == false;</bpmn2:conditionExpression>
    </bpmn2:sequenceFlow>
    <bpmn2:sequenceFlow id="SequenceFlow_4" sourceRef="UserTask_1" targetRef="EndEvent_1"/>
    <bpmn2:sequenceFlow id="SequenceFlow_5" sourceRef="ExclusiveGateway_1" targetRef="EndEvent_2">
      <bpmn2:conditionExpression xsi:type="bpmn2:tFormalExpression" language="http://www.java.com/java">return isAdult == true;</bpmn2:conditionExpression>
    </bpmn2:sequenceFlow>
    <bpmn2:startEvent id="StartEvent_1" name="StartProcess">
      <bpmn2:extensionElements>
        <drools:metaData name="elementname">
          <drools:metaValue>StartProcess</drools:metaValue>
        </drools:metaData>
      </bpmn2:extensionElements>
      <bpmn2:outgoing>SequenceFlow_1</bpmn2:outgoing>
    </bpmn2:startEvent>
    <bpmn2:businessRuleTask id="BusinessRuleTask_1" name="Evaluate person" implementation="http://www.jboss.org/drools/dmn">
      <bpmn2:extensionElements>
        <drools:metaData name="elementname">
          <drools:metaValue>Evaluate person</drools:metaValue>
        </drools:metaData>
      </bpmn2:extensionElements>
      <bpmn2:incoming>SequenceFlow_1</bpmn2:incoming>
      <bpmn2:outgoing>SequenceFlow_2</bpmn2:outgoing>
      <bpmn2:ioSpecification>
        <bpmn2:dataInput id="BusinessRuleTask_1_namespaceInputX" drools:dtype="java.lang.String" itemSubjectRef="_BusinessRuleTask_1_namespaceInputXItem" name="namespace"/>
        <bpmn2:dataInput id="BusinessRuleTask_1_decisionInputX" drools:dtype="java.lang.String" itemSubjectRef="_BusinessRuleTask_1_decisionInputXItem" name="decision"/>
        <bpmn2:dataInput id="BusinessRuleTask_1_modelInputX" drools:dtype="java.lang.String" itemSubjectRef="_BusinessRuleTask_1_modelInputXItem" name="model"/>
        <bpmn2:dataInput id="BusinessRuleTask_1_PersonInputX" drools:dtype="org.acme.Person" itemSubjectRef="_BusinessRuleTask_1_PersonInputXItem" name="Person"/>
        <bpmn2:dataOutput id="BusinessRuleTask_1_isAdultOutputX" drools:dtype="Boolean" itemSubjectRef="_BusinessRuleTask_1_isAdultOutputXItem" name="isAdult"/>
        <bpmn2:inputSet>
          <bpmn2:dataInputRefs>BusinessRuleTask_1_namespaceInputX</bpmn2:dataInputRefs>
          <bpmn2:dataInputRefs>BusinessRuleTask_1_decisionInputX</bpmn2:dataInputRefs>
          <bpmn2:dataInputRefs>BusinessRuleTask_1_modelInputX</bpmn2:dataInputRefs>
          <bpmn2:dataInputRefs>BusinessRuleTask_1_PersonInputX</bpmn2:dataInputRefs>
        </bpmn2:inputSet>
        <bpmn2:outputSet>
          <bpmn2:dataOutputRefs>BusinessRuleTask_1_isAdultOutputX</bpmn2:dataOutputRefs>
        </bpmn2:outputSet>
      </bpmn2:ioSpecification>
      <bpmn2:dataInputAssociation>
        <bpmn2:targetRef>BusinessRuleTask_1_namespaceInputX</bpmn2:targetRef>
        <bpmn2:assignment>
          <bpmn2:from xsi:type="bpmn2:tFormalExpression">https://kie.org/dmn/_F322E39A-1EF2-470E-BD8C-960352D1EA36</bpmn2:from>
          <bpmn2:to xsi:type="bpmn2:tFormalExpression">BusinessRuleTask_1_namespaceInputX</bpmn2:to>
        </bpmn2:assignment>
      </bpmn2:dataInputAssociation>
      <bpmn2:dataInputAssociation>
        <bpmn2:targetRef>BusinessRuleTask_1_decisionInputX</bpmn2:targetRef>
        <bpmn2:assignment>
          <bpmn2:from xsi:type="bpmn2:tFormalExpression">isAdult</bpmn2:from>
          <bpmn2:to xsi:type="bpmn2:tFormalExpression">BusinessRuleTask_1_decisionInputX</bpmn2:to>
        </bpmn2:assignment>
      </bpmn2:dataInputAssociation>
      <bpmn2:dataInputAssociation>
        <bpmn2:targetRef>BusinessRuleTask_1_modelInputX</bpmn2:targetRef>
        <bpmn2:assignment>
          <bpmn2:from xsi:type="bpmn2:tFormalExpression">PersonDecisions</bpmn2:from>
          <bpmn2:to xsi:type="bpmn2:tFormalExpression">BusinessRuleTask_1_modelInputX</bpmn2:to>
        </bpmn2:assignment>
      </bpmn2:dataInputAssociation>
      <bpmn2:dataInputAssociation>
        <bpmn2:sourceRef>person</bpmn2:sourceRef>
        <bpmn2:targetRef>BusinessRuleTask_1_PersonInputX</bpmn2:targetRef>
      </bpmn2:dataInputAssociation>
      <bpmn2:dataOutputAssociation>
        <bpmn2:sourceRef>BusinessRuleTask_1_isAdultOutputX</bpmn2:sourceRef>
        <bpmn2:targetRef>isAdult</bpmn2:targetRef>
      </bpmn2:dataOutputAssociation>
    </bpmn2:businessRuleTask>
    <bpmn2:exclusiveGateway id="ExclusiveGateway_1" name="Exclusive Gateway 1" gatewayDirection="Diverging">
      <bpmn2:extensionElements>
        <drools:metaData name="elementname">
          <drools:metaValue>Exclusive Gateway 1</drools:metaValue>
        </drools:metaData>
      </bpmn2:extensionElements>
      <bpmn2:incoming>SequenceFlow_2</bpmn2:incoming>
      <bpmn2:outgoing>SequenceFlow_5</bpmn2:outgoing>
      <bpmn2:outgoing>SequenceFlow_3</bpmn2:outgoing>
    </bpmn2:exclusiveGateway>
    <bpmn2:userTask id="UserTask_1" name="Special handling for children">
      <bpmn2:extensionElements>
        <drools:metaData name="elementname">
          <drools:metaValue>Special handling for children</drools:metaValue>
        </drools:metaData>
      </bpmn2:extensionElements>
      <bpmn2:incoming>SequenceFlow_3</bpmn2:incoming>
      <bpmn2:outgoing>SequenceFlow_4</bpmn2:outgoing>
      <bpmn2:ioSpecification>
        <bpmn2:dataInput id="UserTask_1_TaskNameInputX" drools:dtype="Object" itemSubjectRef="_UserTask_1_TaskNameInputXItem" name="TaskName"/>
        <bpmn2:dataInput id="UserTask_1_personInputX" drools:dtype="org.acme.Person" itemSubjectRef="_UserTask_1_personInputXItem" name="person"/>
        <bpmn2:dataInput id="UserTask_1_SkippableInputX" drools:dtype="Object" itemSubjectRef="_UserTask_1_SkippableInputXItem" name="Skippable"/>
        <bpmn2:dataInput id="UserTask_1_PriorityInputX" drools:dtype="Object" itemSubjectRef="_UserTask_1_PriorityInputXItem" name="Priority"/>
        <bpmn2:inputSet>
          <bpmn2:dataInputRefs>UserTask_1_TaskNameInputX</bpmn2:dataInputRefs>
          <bpmn2:dataInputRefs>UserTask_1_personInputX</bpmn2:dataInputRefs>
          <bpmn2:dataInputRefs>UserTask_1_SkippableInputX</bpmn2:dataInputRefs>
          <bpmn2:dataInputRefs>UserTask_1_PriorityInputX</bpmn2:dataInputRefs>
        </bpmn2:inputSet>
      </bpmn2:ioSpecification>
      <bpmn2:dataInputAssociation>
        <bpmn2:targetRef>UserTask_1_TaskNameInputX</bpmn2:targetRef>
        <bpmn2:assignment>
          <bpmn2:from xsi:type="bpmn2:tFormalExpression">ChildrenHandling</bpmn2:from>
          <bpmn2:to xsi:type="bpmn2:tFormalExpression">UserTask_1_TaskNameInputX</bpmn2:to>
        </bpmn2:assignment>
      </bpmn2:dataInputAssociation>
      <bpmn2:dataInputAssociation>
        <bpmn2:sourceRef>person</bpmn2:sourceRef>
        <bpmn2:targetRef>UserTask_1_personInputX</bpmn2:targetRef>
      </bpmn2:dataInputAssociation>
      <bpmn2:dataInputAssociation>
        <bpmn2:targetRef>UserTask_1_SkippableInputX</bpmn2:targetRef>
        <bpmn2:assignment>
          <bpmn2:from xsi:type="bpmn2:tFormalExpression">true</bpmn2:from>
          <bpmn2:to xsi:type="bpmn2:tFormalExpression">UserTask_1_SkippableInputX</bpmn2:to>
        </bpmn2:assignment>
      </bpmn2:dataInputAssociation>
      <bpmn2:dataInputAssociation>
        <bpmn2:targetRef>UserTask_1_PriorityInputX</bpmn2:targetRef>
        <bpmn2:assignment>
          <bpmn2:from xsi:type="bpmn2:tFormalExpression">1</bpmn2:from>
          <bpmn2:to xsi:type="bpmn2:tFormalExpression">UserTask_1_PriorityInputX</bpmn2:to>
        </bpmn2:assignment>
      </bpmn2:dataInputAssociation>
    </bpmn2:userTask>
    <bpmn2:endEvent id="EndEvent_1" name="End Event 1">
      <bpmn2:extensionElements>
        <drools:metaData name="elementname">
          <drools:metaValue>End Event 1</drools:metaValue>
        </drools:metaData>
      </bpmn2:extensionElements>
      <bpmn2:incoming>SequenceFlow_4</bpmn2:incoming>
    </bpmn2:endEvent>
    <bpmn2:endEvent id="EndEvent_2" name="End Event 2">
      <bpmn2:extensionElements>
        <drools:metaData name="elementname">
          <drools:metaValue>End Event 2</drools:metaValue>
        </drools:metaData>
      </bpmn2:extensionElements>
      <bpmn2:incoming>SequenceFlow_5</bpmn2:incoming>
    </bpmn2:endEvent>
  </bpmn2:process>
  <bpmndi:BPMNDiagram>
    <bpmndi:BPMNPlane bpmnElement="persons">
      <bpmndi:BPMNShape id="shape_EndEvent_2" bpmnElement="EndEvent_2">
        <dc:Bounds height="56" width="56" x="622" y="201"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape id="shape_EndEvent_1" bpmnElement="EndEvent_1">
        <dc:Bounds height="56" width="56" x="622" y="105"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape id="shape_UserTask_1" bpmnElement="UserTask_1">
        <dc:Bounds height="78" width="134" x="449" y="94"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape id="shape_ExclusiveGateway_1" bpmnElement="ExclusiveGateway_1">
        <dc:Bounds height="56" width="56" x="365" y="105"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape id="shape_BusinessRuleTask_1" bpmnElement="BusinessRuleTask_1">
        <dc:Bounds height="71" width="141" x="180" y="97"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape id="shape_StartEvent_1" bpmnElement="StartEvent_1">
        <dc:Bounds height="56" width="56" x="80" y="105"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNEdge id="edge_shape_ExclusiveGateway_1_to_shape_EndEvent_2" bpmnElement="SequenceFlow_5">
        <di:waypoint x="390" y="155"/>
        <di:waypoint x="393" y="231"/>
        <di:waypoint x="622" y="219"/>
      </bpmndi:BPMNEdge>
      <bpmndi:BPMNEdge id="edge_shape_UserTask_1_to_shape_EndEvent_1" bpmnElement="SequenceFlow_4">
        <di:waypoint x="583" y="133"/>
        <di:waypoint x="622" y="123"/>
      </bpmndi:BPMNEdge>
      <bpmndi:BPMNEdge id="edge_shape_ExclusiveGateway_1_to_shape_UserTask_1" bpmnElement="SequenceFlow_3">
        <di:waypoint x="415" y="130"/>
        <di:waypoint x="449" y="133"/>
      </bpmndi:BPMNEdge>
      <bpmndi:BPMNEdge id="edge_shape_BusinessRuleTask_1_to_shape_ExclusiveGateway_1" bpmnElement="SequenceFlow_2">
        <di:waypoint x="321" y="132.5"/>
        <di:waypoint x="365" y="130"/>
      </bpmndi:BPMNEdge>
      <bpmndi:BPMNEdge id="edge_shape_StartEvent_1_to_shape_BusinessRuleTask_1" bpmnElement="SequenceFlow_1">
        <di:waypoint x="116" y="123"/>
        <di:waypoint x="180" y="132.5"/>
      </bpmndi:BPMNEdge>
    </bpmndi:BPMNPlane>
  </bpmndi:BPMNDiagram>
  <bpmn2:relationship type="BPSimData">
    <bpmn2:extensionElements>
      <bpsim:BPSimData>
        <bpsim:Scenario id="default" name="Simulationscenario">
          <bpsim:ScenarioParameters/>
          <bpsim:ElementParameters elementRef="UserTask_1">
            <bpsim:TimeParameters>
              <bpsim:ProcessingTime>
                <bpsim:NormalDistribution mean="0" standardDeviation="0"/>
              </bpsim:ProcessingTime>
            </bpsim:TimeParameters>
            <bpsim:ResourceParameters>
              <bpsim:Availability>
                <bpsim:FloatingParameter value="0"/>
              </bpsim:Availability>
              <bpsim:Quantity>
                <bpsim:FloatingParameter value="0"/>
              </bpsim:Quantity>
            </bpsim:ResourceParameters>
            <bpsim:CostParameters>
              <bpsim:UnitCost>
                <bpsim:FloatingParameter value="0"/>
              </bpsim:UnitCost>
            </bpsim:CostParameters>
          </bpsim:ElementParameters>
          <bpsim:ElementParameters elementRef="BusinessRuleTask_1">
            <bpsim:TimeParameters>
              <bpsim:ProcessingTime>
                <bpsim:NormalDistribution mean="0" standardDeviation="0"/>
              </bpsim:ProcessingTime>
            </bpsim:TimeParameters>
            <bpsim:ResourceParameters>
              <bpsim:Availability>
                <bpsim:FloatingParameter value="0"/>
              </bpsim:Availability>
              <bpsim:Quantity>
                <bpsim:FloatingParameter value="0"/>
              </bpsim:Quantity>
            </bpsim:ResourceParameters>
            <bpsim:CostParameters>
              <bpsim:UnitCost>
                <bpsim:FloatingParameter value="0"/>
              </bpsim:UnitCost>
            </bpsim:CostParameters>
          </bpsim:ElementParameters>
          <bpsim:ElementParameters elementRef="StartEvent_1">
            <bpsim:TimeParameters>
              <bpsim:ProcessingTime>
                <bpsim:NormalDistribution mean="0" standardDeviation="0"/>
              </bpsim:ProcessingTime>
            </bpsim:TimeParameters>
          </bpsim:ElementParameters>
        </bpsim:Scenario>
      </bpsim:BPSimData>
    </bpmn2:extensionElements>
    <bpmn2:source>_J4ElsVJgEDiScotxwBQ14Q</bpmn2:source>
    <bpmn2:target>_J4ElsVJgEDiScotxwBQ14Q</bpmn2:target>
  </bpmn2:relationship>
</bpmn2:definitions>
----

To create this example BPMN process in VSCode using the {PRODUCT} BPMN modeler, follow these steps:

.. Open the empty `PersonProcess.bpmn2` file and in the upper-right corner of the BPMN modeler, click the *Properties* icon and define the following properties:
* *Process*: Set the following values:
** *Name*: `Person Process`
** *ID*: `persons`
** *Package*: `org.acme`
* *Process Data*: Add the following process variables:
** `person` with the type `org.acme.Person` (Use the *Custom* data type option to define the custom type.)
** `isAdult` with the type `Boolean`
.. In the left palette, select *Activities* -> *Business Rule*, drag the task to the canvas, and link to it from the start event.
.. Select the business rule task and define the following properties:

* *General*: Set the rule task *Name* to `Evaluate person`.
* *Implementation/Execution*: Set the following values:
** *Rule Language*: `DMN`
** *Namespace*: The `namespace` property value from the `PersonDecisions.dmn` file that you created previously, such as `https://kie.org/dmn/_F322E39A-1EF2-470E-BD8C-960352D1EA36`
** *Decision Name*: `isAdult`
** *DMN Model Name*: `PersonDecisions`
* *Data Assignments*: Add the following assignments:
** *Data Input*: Add a data input with the name `Person`, with the type `org.acme.Person`, and with the source `person`.
** *Data Output*: Add a data output with the name `isAdult`, with the type `Boolean`, and with the source `isAdult`.
.. In the left palette, select *Gateways* -> *Exclusive*, drag the gateway to the canvas, and link to it from the rule task.
.. In the left palette, select *Activities* -> *User*, drag the user task to the canvas, and link to it from the exclusive gateway.
.. Select the user task and define the following properties:

* *General*: Set the user task *Name* to `Special handling for children`.
* *Implementation/Execution*: Set the *Task Name* to `ChildrenHandling`, and add a data input with the name `person`, the type `org.acme.Person`, and the source `person`.
.. In the left palette, select *End Events* -> *End*, drag two end events to the canvas, and link to one end event from the user task and to the other end event from the exclusive gateway.
.. Select the connector that connects the exclusive gateway to the end event and for the *Implementation/Execution* property, set the *Condition Expression* to `Java` and enter the condition `return isAdult == true;`.
.. Select the connector that connects the exclusive gateway to the user task and for the *Implementation/Execution* property, set the *Condition Expression* to `Java` and enter the condition to `return isAdult == false;`
.. Save the BPMN process file.
--

[id="proc-kogito-designing-app-rule-units_{context}"]
=== Using DRL rule units as an alternative decision service

[role="_abstract"]
As an alternative to using Decision Model and Notation (DMN) to define this example decision service, you can also use a Drools Rule Language (DRL) file implemented as a rule unit.

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 {URL_DECISION_SERVICES}#con-drl-rule-units_kogito-drl-rules[_{DECISION_SERVICES}_].

.Procedure
. In the `src/main/resources` folder of your example {PRODUCT} project, instead of using a DMN file, add the following `PersonRules.drl` file:
+
--
.Example `PersonRules` DRL file
[source]
----
package org.acme
unit PersonRules;

import org.acme.Person;

rule isAdult
	when
		$person: /person[ age > 18 ]
	then
    modify($person) {
    	setAdult(true)
    };
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`. This is the rule unit that you define as part of the business rule task in the example BPMN process. 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
[source]
----
package org.acme
unit PersonRules;

import org.acme.Person;

rule isAdult
	when
		$person: Person(age > 18) from person
	then
    modify($person) {
    	setAdult(true)
    };
end
----
--
. In the `src/main/resources` folder, use the {PRODUCT} BPMN modeler in VSCode to open the `PersonProcess.bpmn2` process diagram that you created.
. Select the `Evaluate person` business rule task and modify the following properties:

* *Implementation/Execution*: Set the following values:
** *Rule Language*: `DRL` (instead of `DMN`)
** *Rule Flow Group*: `unit:org.acme.PersonRules`
+
This rule unit syntax in the *Rule Flow Group* field specifies that you are using the `org.acme.PersonRules` rule unit instead of a traditional rule flow group. This is the rule unit that you referenced in the example DRL file. When you build the project, the business process implicitly declares the rule unit as part of the business rule task to execute the DRL file.
* *Data Assignments*: Open the assignment settings and change the data input *Name* to `person` (instead of `Person`). This accommodates the input variable syntax required by the DRL file.
. Select the connector that connects the exclusive gateway to the end event and for the *Implementation/Execution* property, verify that the *Condition Expression* is set to `Java` and change the condition to `return person.isAdult();`.
. Select the connector that connects the exclusive gateway to the user task and for the *Implementation/Execution* property, verify that the *Condition Expression* is set to `Java` and change the condition `return ! person.isAdult();`.
. Save the process file to update the model.

[id="proc-kogito-testing-decision-logic_{context}"]
== Testing the decision logic for a {PRODUCT} service using test scenarios

[role="_abstract"]
As you develop business decisions in your {PRODUCT} services, you can use test scenarios to validate the functionality of your decisions before you begin running and using your {PRODUCT} services. With a test scenario, you use data from your project to set given conditions and expected results based on one or more defined business decisions. When you run the scenario, the expected results and actual results of the decision instance are compared. If the expected results match the actual results, the test is successful. If the expected results do not match the actual results, then the test fails.

You define test scenarios in `.scesim` (scenario simulation) files that you can model in Visual Studio Code (VSCode) using the *{VSCODE_EXTENSION}* VSCode extension. You can use one or multiple `.scesim` files in your {PRODUCT} project, and each `.scesim` file can contain one or multiple test scenarios based on the defined decision data.

The example for this procedure uses a basic `PersonDecisionsTest.scesim` test scenario file that validates the decision logic in the example `PersonDecisions.dmn` Decision Model and Notation (DMN) model that you created previously.

IMPORTANT: Test scenarios in {PRODUCT} currently support DMN decision services only. Test scenarios will support Drools Rule Language (DRL) decision services in a future release.

.Prerequisites
* You have created the `PersonDecisions.dmn` DMN model that determines whether a specified person is an adult or is underage. For more information about this DMN model, see xref:proc-kogito-designing-app_kogito-creating-running[].

.Procedure
. In the Maven project that contains your {PRODUCT} decision services, add the following dependency to the `pom.xml` file to enable test scenario execution for your project:
+
.Dependency to enable test scenario execution
[source,xml]
----
<dependency>
  <groupId>org.drools</groupId>
  <artifactId>drools-scenario-simulation</artifactId>
  <scope>test</scope>
</dependency>
----
. Navigate to the `src/main` folder of the project and create a `test` folder with the following subfolders. If you have an existing `test` folder structure, you can adapt the steps that follow according to your project layout.
+
.Test folder structure for test scenarios
[source]
----
src/main/test/
          └── java/testscenario
          └── resources
----
. Navigate to the `test/java/testscenario` folder and add the following `KogitoScenarioJunitActivatorTest.java` class:
+
--
.Activator class for test scenarios
[source,java]
----
package testscenario;

@org.junit.runner.RunWith(org.kogito.scenariosimulation.runner.KogitoJunitActivator.class)
public class KogitoScenarioJunitActivatorTest {

}
----

This activator class is a custom https://junit.org/junit5/[JUnit 5] runner that enables the execution of test scenario files in your {PRODUCT} project. When you run test scenarios, this class loads all `.scesim` files available in the project and executes them. For each row (scenario) in a test scenario file, the activator class generates a JUnit test result.
--
. Navigate to the `test/resources` folder and add the following `PersonDecisionsTest.scesim` test scenario file:
+
--
.Example test scenarios for `PersonDecisions` DMN decision logic
image::kogito/creating-running/kogito-test-scenario-example-person.png[Image of PersonDecisionsTest test scenario]

The *GIVEN* columns specify input conditions based on the corresponding decision service. The *EXPECT* column specifies the expected results of the decision service based on the defined *GIVEN* conditions. Each row in the table is a defined scenario with example values for the *GIVEN* and *EXPECT* definitions to test the decision logic of the corresponding decision service.

This example test scenario file tests the decision logic for the following `PersonDecisions.dmn` model that you created previously. This DMN model determines whether a specified person is an adult or is underage.

.Example `PersonDecisions` DMN decision requirements diagram (DRD)
image::kogito/creating-running/kogito-dmn-example-person.png[Image of PersonDecisions decision diagram]

.Example DMN boxed expression for `isAdult` decision
image::kogito/creating-running/kogito-dmn-example-person-logic.png[Image of PersonDecisions decision table]

In VSCode (recommended), you can add the *{VSCODE_EXTENSION}* VSCode extension to design the test scenarios with the test scenario modeler.

To create these example test scenarios quickly, you can copy the following `PersonDecisionsTest.scesim` file content:

.Example test scenario file
[source,xml]
----
<ScenarioSimulationModel version="1.8">
  <simulation>
    <scesimModelDescriptor>
      <factMappings>
        <FactMapping>
          <expressionElements/>
          <expressionIdentifier>
            <name>Index</name>
            <type>OTHER</type>
          </expressionIdentifier>
          <factIdentifier>
            <name>#</name>
            <className>java.lang.Integer</className>
          </factIdentifier>
          <className>java.lang.Integer</className>
          <factAlias>#</factAlias>
          <columnWidth>70</columnWidth>
          <factMappingValueType>NOT_EXPRESSION</factMappingValueType>
        </FactMapping>
        <FactMapping>
          <expressionElements/>
          <expressionIdentifier>
            <name>Description</name>
            <type>OTHER</type>
          </expressionIdentifier>
          <factIdentifier>
            <name>Scenario description</name>
            <className>java.lang.String</className>
          </factIdentifier>
          <className>java.lang.String</className>
          <factAlias>Scenario description</factAlias>
          <columnWidth>300</columnWidth>
          <factMappingValueType>NOT_EXPRESSION</factMappingValueType>
        </FactMapping>
        <FactMapping>
          <expressionElements>
            <ExpressionElement>
              <step>Person</step>
            </ExpressionElement>
            <ExpressionElement>
              <step>Age</step>
            </ExpressionElement>
          </expressionElements>
          <expressionIdentifier>
            <name>1|1</name>
            <type>GIVEN</type>
          </expressionIdentifier>
          <factIdentifier>
            <name>Person</name>
            <className>Person</className>
          </factIdentifier>
          <className>number</className>
          <factAlias>Person</factAlias>
          <expressionAlias>Age</expressionAlias>
          <genericTypes/>
          <columnWidth>114</columnWidth>
          <factMappingValueType>NOT_EXPRESSION</factMappingValueType>
        </FactMapping>
        <FactMapping>
          <expressionElements>
            <ExpressionElement>
              <step>Person</step>
            </ExpressionElement>
            <ExpressionElement>
              <step>Name</step>
            </ExpressionElement>
          </expressionElements>
          <expressionIdentifier>
            <name>1|2</name>
            <type>GIVEN</type>
          </expressionIdentifier>
          <factIdentifier>
            <name>Person</name>
            <className>Person</className>
          </factIdentifier>
          <className>string</className>
          <factAlias>Person</factAlias>
          <expressionAlias>Name</expressionAlias>
          <genericTypes/>
          <columnWidth>114</columnWidth>
          <factMappingValueType>NOT_EXPRESSION</factMappingValueType>
        </FactMapping>
        <FactMapping>
          <expressionElements>
            <ExpressionElement>
              <step>isAdult</step>
            </ExpressionElement>
          </expressionElements>
          <expressionIdentifier>
            <name>1|4</name>
            <type>EXPECT</type>
          </expressionIdentifier>
          <factIdentifier>
            <name>isAdult</name>
            <className>isAdult</className>
          </factIdentifier>
          <className>boolean</className>
          <factAlias>isAdult</factAlias>
          <expressionAlias>value</expressionAlias>
          <genericTypes/>
          <columnWidth>114</columnWidth>
          <factMappingValueType>NOT_EXPRESSION</factMappingValueType>
        </FactMapping>
      </factMappings>
    </scesimModelDescriptor>
    <scesimData>
      <Scenario>
        <factMappingValues>
          <FactMappingValue>
            <factIdentifier>
              <name>Scenario description</name>
              <className>java.lang.String</className>
            </factIdentifier>
            <expressionIdentifier>
              <name>Description</name>
              <type>OTHER</type>
            </expressionIdentifier>
            <rawValue class="string">Is an adult</rawValue>
          </FactMappingValue>
          <FactMappingValue>
            <factIdentifier>
              <name>Person</name>
              <className>Person</className>
            </factIdentifier>
            <expressionIdentifier>
              <name>1|1</name>
              <type>GIVEN</type>
            </expressionIdentifier>
            <rawValue class="string">20</rawValue>
          </FactMappingValue>
          <FactMappingValue>
            <factIdentifier>
              <name>Person</name>
              <className>Person</className>
            </factIdentifier>
            <expressionIdentifier>
              <name>1|2</name>
              <type>GIVEN</type>
            </expressionIdentifier>
            <rawValue class="string">"John Quark"</rawValue>
          </FactMappingValue>
          <FactMappingValue>
            <factIdentifier>
              <name>isAdult</name>
              <className>isAdult</className>
            </factIdentifier>
            <expressionIdentifier>
              <name>1|4</name>
              <type>EXPECT</type>
            </expressionIdentifier>
            <rawValue class="string">true</rawValue>
          </FactMappingValue>
          <FactMappingValue>
            <factIdentifier>
              <name>#</name>
              <className>java.lang.Integer</className>
            </factIdentifier>
            <expressionIdentifier>
              <name>Index</name>
              <type>OTHER</type>
            </expressionIdentifier>
            <rawValue class="string">1</rawValue>
          </FactMappingValue>
        </factMappingValues>
      </Scenario>
      <Scenario>
        <factMappingValues>
          <FactMappingValue>
            <factIdentifier>
              <name>Scenario description</name>
              <className>java.lang.String</className>
            </factIdentifier>
            <expressionIdentifier>
              <name>Description</name>
              <type>OTHER</type>
            </expressionIdentifier>
            <rawValue class="string">Is underage</rawValue>
          </FactMappingValue>
          <FactMappingValue>
            <factIdentifier>
              <name>Person</name>
              <className>Person</className>
            </factIdentifier>
            <expressionIdentifier>
              <name>1|1</name>
              <type>GIVEN</type>
            </expressionIdentifier>
            <rawValue class="string">15</rawValue>
          </FactMappingValue>
          <FactMappingValue>
            <factIdentifier>
              <name>Person</name>
              <className>Person</className>
            </factIdentifier>
            <expressionIdentifier>
              <name>1|2</name>
              <type>GIVEN</type>
            </expressionIdentifier>
            <rawValue class="string">"Jenny Quark"</rawValue>
          </FactMappingValue>
          <FactMappingValue>
            <factIdentifier>
              <name>isAdult</name>
              <className>isAdult</className>
            </factIdentifier>
            <expressionIdentifier>
              <name>1|4</name>
              <type>EXPECT</type>
            </expressionIdentifier>
            <rawValue class="string">false</rawValue>
          </FactMappingValue>
          <FactMappingValue>
            <factIdentifier>
              <name>#</name>
              <className>java.lang.Integer</className>
            </factIdentifier>
            <expressionIdentifier>
              <name>Index</name>
              <type>OTHER</type>
            </expressionIdentifier>
            <rawValue class="string">2</rawValue>
          </FactMappingValue>
        </factMappingValues>
      </Scenario>
    </scesimData>
  </simulation>
  <background>
    <scesimModelDescriptor>
      <factMappings>
        <FactMapping>
          <expressionElements/>
          <expressionIdentifier>
            <name>1|1</name>
            <type>GIVEN</type>
          </expressionIdentifier>
          <factIdentifier>
            <name>Empty</name>
            <className>java.lang.Void</className>
          </factIdentifier>
          <className>java.lang.Void</className>
          <factAlias>INSTANCE 1</factAlias>
          <expressionAlias>PROPERTY 1</expressionAlias>
          <columnWidth>114</columnWidth>
          <factMappingValueType>NOT_EXPRESSION</factMappingValueType>
        </FactMapping>
      </factMappings>
    </scesimModelDescriptor>
    <scesimData>
      <BackgroundData>
        <factMappingValues>
          <FactMappingValue>
            <factIdentifier>
              <name>Empty</name>
              <className>java.lang.Void</className>
            </factIdentifier>
            <expressionIdentifier>
              <name>1|1</name>
              <type>GIVEN</type>
            </expressionIdentifier>
          </FactMappingValue>
        </factMappingValues>
      </BackgroundData>
    </scesimData>
  </background>
  <settings>
    <dmnFilePath>src/main/resources/PersonDecisions.dmn</dmnFilePath>
    <type>DMN</type>
    <dmnNamespace>https://kie.org/dmn/_F322E39A-1EF2-470E-BD8C-960352D1EA36</dmnNamespace>
    <dmnName>PersonDecisions</dmnName>
    <skipFromBuild>false</skipFromBuild>
    <stateless>false</stateless>
  </settings>
  <imports>
    <imports/>
  </imports>
</ScenarioSimulationModel>
----

To create this example test scenario file in VSCode using the {PRODUCT} test scenario modeler, follow these steps:

.. Open the empty `PersonDecisionsTest.scesim` file and in the *Create Test Scenario* window that appears, set the *Source type* to *DMN*, select the `PersonDecisions.dmn` DMN model from the drop-down options, and click *Create*.
+
.Create test scenario definition
image::kogito/creating-running/kogito-test-scenario-example-person-create.png[Image of Create Test Scenario window]
+
The test scenario modeler automatically generates a scenario template based on the available DMN data types and fields that you defined in the DMN model.
+
You can right-click the relevant header cells to insert or delete columns as needed to modify the table structure. You can also select the relevant header cells to modify or insert data objects from the *Test Tools* panel in the right toolbar.
.. For this example, modify the generated test scenario header cells and specified data objects as needed to create the following test scenario template. Use the *Test Tools* panel in the right toolbar to select and insert the data objects as needed. Many of the header cell values might already be defined for you.
+
* *GIVEN*: Verify that the first header cell (instance) is set to the *Person* data object and that the subheader cells (properties) are set to the *Age* and *Name* data objects. Delete any other columns under *GIVEN* that were automatically generated, if applicable.
* *EXPECT*: Verify that the first header cell (instance) is set to the *isAdult* data object and that the subheader cell (property) is set to the *value* data object. Delete any other columns under *EXPECT* that were automatically generated, if applicable.
+
.Define test scenario header cells
image::kogito/creating-running/kogito-test-scenario-example-person-headers-create.png[Image of test scenario template]
.. In row 1, create a test scenario with the following values:
+
* *Scenario description*: `Is an adult`
* *GIVEN*: Set the following values:
** *Person* -> *Age*: `20`
** *Person* -> *Name*: `John Quark`
* *EXPECT*: Set the following value:
** *isAdult* -> *value*: `true`

+
This example scenario tests whether the person John Quark with 20 years of age is correctly identified by the `isAdult` DMN decision as an adult (`true`), based on the decision logic that adults are more than 18 years old.
.. Right-click any cell in row 1, select *Insert row below*, and in row 2, create another test scenario with the following values:
+
* *Scenario description*: `Is underage`
* *GIVEN*: Set the following values:
** *Person* -> *Age*: `15`
** *Person* -> *Name*: `Jenny Quark`
* *EXPECT*: Set the following value:
** *isAdult* -> *value*: `false`

+
This example scenario tests whether the person Jenny Quark with 15 years of age is correctly identified by the `isAdult` DMN decision as not an adult (`false`), based on the decision logic that adults are more than 18 years old.
.. Save the test scenario file.
--
. After you define and save the test scenarios, in a command terminal, navigate to the project that contains your {PRODUCT} decision service and test scenarios and enter the following command to run the test scenarios:
+
--
.Run the test scenarios
[source]
----
mvn clean test
----

A summary of the test scenario execution appears in the command terminal, and detailed reports are generated in the `target/surefire-reports` folder of your {PRODUCT} project.

In the following example output, the test scenarios were executed successfully and encountered no errors:

.Terminal output for successful test scenarios
[source]
----
[INFO] --- maven-surefire-plugin:2.22.1:test (default-test) @ sample-kogito ---
[INFO]
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running testscenario.KogitoScenarioJunitActivatorTest
./target/classes/PersonDecisions.dmn
./src/main/resources/PersonDecisions.dmn
./target/classes/PersonDecisions.dmn
./src/main/resources/PersonDecisions.dmn
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.535 s - in testscenario.KogitoScenarioJunitActivatorTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  52.884 s
[INFO] Finished at: 2020-05-05T15:19:53-04:00
[INFO] ------------------------------------------------------------------------
----

The expected results defined in the test scenarios matched the actual results of the `isAdult` DMN decision instance in the `PersonDecisions.dmn` file. This match of expected and actual results for the decision instance means that the decision logic functions as intended.

In the following example output, the test scenarios were executed and the `Is underage` scenario encountered an error:

.Terminal output for a test scenario that encountered a decision error
[source]
----
[INFO] --- maven-surefire-plugin:2.22.1:test (default-test) @ sample-kogito ---
[INFO]
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running testscenario.KogitoScenarioJunitActivatorTest
./target/classes/PersonDecisions.dmn
./src/main/resources/PersonDecisions.dmn
./target/classes/PersonDecisions.dmn
./src/main/resources/PersonDecisions.dmn
[ERROR] Tests run: 2, Failures: 0, Errors: 1, Skipped: 0, Time elapsed: 0.534 s <<< FAILURE! - in testscenario.KogitoScenarioJunitActivatorTest
[ERROR] #2: Is underage  Time elapsed: 0.06 s  <<< ERROR!
org.drools.scenariosimulation.backend.runner.IndexedScenarioException: #2: Scenario 'Is underage' failed(/home/jsmith/sample-kogito/target/test-classes/PersonDecisionsTest.scesim)
Caused by: org.drools.scenariosimulation.backend.runner.ScenarioException: Scenario 'Is underage' failed

[INFO]
[INFO] Results:
[INFO]
[ERROR] Errors:
[ERROR]   KogitoScenarioJunitActivatorTest » IndexedScenario #2: Scenario 'Is underage' ...
[INFO]
[ERROR] Tests run: 2, Failures: 0, Errors: 1, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  6.521 s
[INFO] Finished at: 2020-05-05T15:26:10-04:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:2.22.1:test (default-test) on project sample-kogito: There are test failures.
[ERROR]
[ERROR] Please refer to /home/jsmith/sample-kogito/target/surefire-reports for the individual test results.
[ERROR] Please refer to dump files (if any exist) [date].dump, [date]-jvmRun[N].dump and [date].dumpstream.
----

The expected results defined in the `Is underage` test scenario did not match the actual results of the `isAdult` DMN decision instance in the `PersonDecisions.dmn` file. This mismatch of expected and actual results for the decision instance means that either the test scenario identified a flaw in the decision logic or the test scenario is incorrectly defined. In this case, the `Is underage` test scenario was intentionally modified incorrectly with an age of `20` instead of an age of `18` or less. Reverting the age to `15` as shown in the previous example resolves the error.
--

[id="proc-kogito-running-app_{context}"]
== Running a {PRODUCT} service

[role="_abstract"]
After you design the business decisions and processes for your {PRODUCT} service, you can run your Quarkus or Spring Boot application in one of the following modes:

* *Development mode*: For local testing. On Quarkus, development mode also offers live reload of your processes and decisions in your running applications for advanced debugging.
* *JVM mode*: For compatibility with a Java virtual machine (JVM).
ifdef::KOGITO-COMM[]
* *Native mode*: (Quarkus only, requires GraalVM or Mandrel) For direct binary execution as native code.
endif::[]

.Procedure
In a command terminal, navigate to the project that contains your {PRODUCT} service and enter one of the following commands, depending on your preferred run mode and application environment:

* For development mode:
+
--
.On Quarkus
[source]
----
$ mvn clean compile quarkus:dev
----

.On Spring Boot
[source]
----
$ mvn clean compile spring-boot:run
----
--
* For JVM mode:
+
--
.On Quarkus
[source]
----
$ mvn clean package
$ java -jar target/quarkus-app/quarkus-run.jar
----
.On Spring Boot
[source]
----
$ mvn clean package
$ java -jar target/sample-kogito-1.0-SNAPSHOT-runner.jar
----
--
ifdef::KOGITO-COMM[]
* For native mode (requires GraalVM):
+
--
.On Quarkus only
[source]
----
$ mvn clean package -Dnative
$ ./target/sample-kogito-1.0-SNAPSHOT-runner
----
--

[NOTE]
========

Alternatively, you can use a container builder image. You do not need to install GraalVM because a container containing GraalVM is pulled automatically. Note that the executable targets a Linux kernel by default. For example:

--
.On Quarkus only (GraalVM native build using container)
[source]
----
$ mvn clean package -Dnative -Dquarkus.native.container-build
----
--

To use Mandrel instead of GraalVM, run the following command:

--
.On Quarkus only (Mandrel native build using container)
[source]
----
$ mvn clean package -Dnative -Dquarkus.native.container-build -Dquarkus.native.builder-image=quay.io/quarkus/ubi-quarkus-mandrel:23.0.6-java17
----
--

========


For further information about building a native image, see https://quarkus.io/guides/building-native-image#container-runtime[Quarkus - Building a Native Executable].

endif::[]

[id="proc-kogito-interacting-app_{context}"]
== Interacting with a running {PRODUCT} service

[role="_abstract"]
After your {PRODUCT} service is running, you can send REST API requests to interact with your application and execute your services according to how you set up the application.

This example tests the `/persons` REST API endpoint that is automatically generated based on the `PersonProcess.bpmn2` business process, according to 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)
[source,json]
----
{
  "person": {
    "name": "John Quark",
    "age": 20
  }
}
----

.Example curl command to add an adult
[source]
----
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)
[source,json]
----
{
  "id": "3af806dd-8819-4734-a934-728f4c819682",
  "person": {
    "name": "John Quark",
    "age": 20,
    "adult": false
  },
  "isAdult": true
}
----

.Swagger UI to interact with all application endpoints (such as \http://localhost:8080/q/swagger-ui or \http://localhost:8080/swagger-ui.html)
image::kogito/creating-running/kogito-swagger-example.png[Image of Swagger UI for example application]

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 {PRODUCT} service and use any of the following curl commands with JSON requests to interact with your running service:

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
[source]
----
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
[source]
----
{"id":"3af806dd-8819-4734-a934-728f4c819682","person":{"name":"John Quark","age":20,"adult":false},"isAdult":true}
----
--
* Add an underage person:
+
--
.Example request
[source]
----
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
[source]
----
{"id":"8eef502b-012b-4628-acb7-73418a089c08","person":{"name":"Jenny Quark","age":15,"adult":false},"isAdult":false}
----
--
* View active process instances:
+
--
.Example request
[source]
----
curl -X GET http://localhost:8080/persons -H 'content-type: application/json' -H 'accept: application/json'
----

.Example response
[source]
----
[{"id":"8eef502b-012b-4628-acb7-73418a089c08","person":{"name":"Jenny Quark","age":15,"adult":false},"isAdult":false}]
----
--
* View process instance details using the returned process UUID:
+
--
.Example request
[source]
----
curl -X GET http://localhost:8080/persons/8eef502b-012b-4628-acb7-73418a089c08/tasks -H 'content-type: application/json' -H 'accept: application/json'
----

.Example response (JSON)
[source]
----
{"cdec4241-d676-47de-8c55-4ee4f9598bac":"ChildrenHandling"}
----
--
* View task instance details using the returned process and task UUIDs:
+
--
.Example request
[source]
----
curl -X GET http://localhost:8080/persons/8eef502b-012b-4628-acb7-73418a089c08/ChildrenHandling/cdec4241-d676-47de-8c55-4ee4f9598bac -H 'content-type: application/json' -H 'accept: application/json'
----

.Example response
[source]
----
{"person":{"name":"Jenny Quark","age":15,"adult":false},"name":"ChildrenHandling","id":"cdec4241-d676-47de-8c55-4ee4f9598bac"}
----
--
* Complete the evaluation using the returned UUIDs:
+
--
.Example request
[source]
----
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 '{}'
----
--

[id="ref-kogito-glossary_{context}"]
== {PRODUCT} glossary of terms

[role="_abstract"]
This glossary defines terms, concepts, or components that are referenced frequently in {PRODUCT} documentation or that have a unique meaning or function in {PRODUCT}.

BPMN model::
A definition of a business process workflow based on the https://www.omg.org/spec/BPMN/2.0/About-BPMN[Business Process Model and Notation (BPMN) specification]. BPMN is a standard established by the Object Management Group (OMG) for describing and modeling business processes. BPMN defines an XML schema that enables BPMN models to be shared between BPMN-compliant platforms and across organizations so that business analysts and business process developers can collaborate in designing and implementing BPMN process services. The BPMN standard is similar to and can be used together with the Decision Model and Notation (DMN) standard for designing and modeling business decisions.
+
[role="_additional-resources"]
.Additional resources
* {URL_PROCESS_SERVICES}#chap-kogito-developing-process-services[_{PROCESS_SERVICES}_]

business domain API::
An API that your business develops and implements within business applications that contain {PRODUCT} services.

business models::
The collection of BPMN process models, DMN decision models, DRL rules, XLS decision tables, and any other assets that define the business logic for a {PRODUCT} service.

CloudEvents format::
A specification for describing event data in a common way. {PRODUCT} runtime events for messages, processes, tasks, and other application activities are published in https://cloudevents.io/[CloudEvents] format so that they can be consumed efficiently by other entities, such as the {PRODUCT} Data Index Service.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#con-kogito-runtime-events_kogito-configuring[_{PRODUCT} runtime events_]
* {URL_CONFIGURING_KOGITO}#con-data-index-service_kogito-configuring[_{PRODUCT} Data Index Service_]

decision table::
A set of business rules defined in a tabular format. Each row in a decision table is a rule, and each column is a condition, an action, or another rule attribute.
+
[role="_additional-resources"]
.Additional resources
* {URL_DECISION_SERVICES}#con-decision-tables_kogito-decision-tables[_Designing a decision service using spreadsheet decision tables_]

development mode::
A project build option that provides a fast feedback loop from code changes to a running system using hot reload. Development mode also enables debugging tools such as Swagger in {PRODUCT} runtime services.
+
[role="_additional-resources"]
.Additional resources
* {URL_CREATING_RUNNING}#proc-kogito-running-app_kogito-creating-running[_Running a {PRODUCT} service_]
* https://quarkus.io/guides/maven-tooling[_Quarkus - Building applications with Maven_]

DRL rule::
A definition of a business rule in Drools Rule Language (DRL) format. DRL is a notation established by the https://www.drools.org/[Drools] open source business automation project for defining and describing business rules.
+
[role="_additional-resources"]
.Additional resources
* {URL_DECISION_SERVICES}#con-drl_kogito-drl-rules[_Designing a decision service using DRL rules_]

DRL rule unit::
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.
+
[role="_additional-resources"]
.Additional resources
* {URL_DECISION_SERVICES}#con-drl-rule-units_kogito-drl-rules[_Rule units in DRL_]

DMN model::
A definition of a business decision flow based on the https://www.omg.org/spec/DMN[Decision Model and Notation (DMN) specification]. DMN is a standard established by the Object Management Group (OMG) for describing and modeling operational decisions. DMN defines an XML schema that enables DMN models to be shared between DMN-compliant platforms and across organizations so that business analysts and business rules developers can collaborate in designing and implementing DMN decision services. The DMN standard is similar to and can be used together with the Business Process Model and Notation (BPMN) standard for designing and modeling business processes.
+
[role="_additional-resources"]
.Additional resources
* {URL_DECISION_SERVICES}#con-dmn_kogito-dmn-models[_Designing a decision service using DMN models_]

event listener::
A procedure or function in a program that reacts to a specified event, such as a completed node in a process or an executed decision.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#proc-event-listeners-registering_kogito-configuring[_Registering event listeners_]

intelligent application::
An optimized, integrated solution that uses {PRODUCT} services to implement business-domain knowledge.

{PRODUCT} Audit Investigation Console::
A user interface for monitoring and investigating Decision Model and Notation (DMN) model executions in {PRODUCT}.
+
[role="_additional-resources"]
.Additional resources
* {URL_DECISION_SERVICES}#con-audit-console_kogito-dmn-models[_{PRODUCT} Audit Investigation Console_]


////
//@comment: Excluding for now due to current build issues with the extension and we aren't using it at this point. (Stetson, 2 Apr 2020)
{PRODUCT} Quarkus extension::
An extension required to generate and build a Maven project for {PRODUCT} runtime services on the Quarkus Java framework. You can add the {PRODUCT} extension during project creation using the Quarkus Maven plugin or using the https://code.quarkus.io/[Code with Quarkus] extension manager.
////

{PRODUCT} Data Index Service::
A dedicated service in {PRODUCT} that stores all {PRODUCT} events related to processes, tasks, and domain data. The Data Index Service uses Apache Kafka messaging to consume CloudEvents messages from {PRODUCT} services, and then indexes the returned data for future GraphQL queries and stores the data in the Infinispan or MongoDB persistence store. The Data Index Service is at the core of all {PRODUCT} search, insight, and management capabilities.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#con-data-index-service_kogito-configuring[_{PRODUCT} Data Index Service_]

{PRODUCT} domain-specific service::
A business automation service for your business domain that you create using {PRODUCT}. You define the logic of this service using BPMN process models, DMN decision models, or other business models, and any other supported runtime configurations. In {PRODUCT} documentation, the general term for _{PRODUCT} services_ that you create refers to this type of service.

{PRODUCT} Explainability Service::
A dedicated service in {PRODUCT} that provides an explanation for the decisions made in {PRODUCT} services, in conjunction with the _{PRODUCT} Trusty Service_.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#con-trusty-service_kogito-configuring[_{PRODUCT} Trusty Service and Explainability Service_]

{PRODUCT} Jobs Service::
A dedicated service in {PRODUCT} for scheduling BPMN process events that are configured to be executed at a specified time. These time-based events in a process model are known as _jobs_. The Jobs Service does not execute a job, but triggers a callback that might be an HTTP request on a given endpoint specified for the job request or any other configured callback. The Jobs Service receives requests for job scheduling and then sends a request at the time specified on the job request.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#con-jobs-service_kogito-configuring[_{PRODUCT} Jobs Service_]

{PRODUCT} Management Console::
A user interface for viewing the state of all available {PRODUCT} services and managing process instances.
+
[role="_additional-resources"]
.Additional resources
* {URL_PROCESS_SERVICES}#con-management-console_kogito-developing-process-services[_{PRODUCT} Management Console_]

{PRODUCT} runtime event::
A record of a significant change of state in the application domain at a point in time. {PRODUCT} emits runtime events as a result of successfully executed requests, or _units of work_, in a process instance or task instance in a process. {PRODUCT} can use these events to notify third parties about changes to the BPMN process instance and its data.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#con-kogito-runtime-events_kogito-configuring[_{PRODUCT} runtime events_]

{PRODUCT} runtime persistence::
An optional capability for preserving {PRODUCT} process data in your services across application restarts. {PRODUCT} persistence is based on https://infinispan.org/[Infinispan] and enables you to configure key-value storage definitions to persist data, such as active process nodes and process instance variables. Alternatively, https://www.mongodb.com/[MongoDB] can be used.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#con-persistence_kogito-configuring[_Persistence in {PRODUCT}_]

{PRODUCT} supporting services::
The collection of middleware infrastructure services and other dedicated services that help you build additional functionality in the {PRODUCT} domain-specific services that you develop. Key middleware infrastructure services in {PRODUCT} include Infinispan, MongoDB, or Kafka Streams persistence, and Apache Kafka reactive messaging. Dedicated services provided by {PRODUCT} include the {PRODUCT} Data Index Service, Jobs Service, Trusty Service, and Explainability Service.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#con-data-index-service_kogito-configuring[_{PRODUCT} Data Index Service_]
* {URL_CONFIGURING_KOGITO}#con-jobs-service_kogito-configuring[_{PRODUCT} Jobs Service_]
* {URL_CONFIGURING_KOGITO}#con-trusty-service_kogito-configuring[_{PRODUCT} Trusty Service and Explainability Service_]
* {URL_CONFIGURING_KOGITO}#proc-infinispan-persistence-enabling_kogito-configuring[_Enabling Infinispan persistence for {PRODUCT} services_]
* {URL_CONFIGURING_KOGITO}#proc-mongodb-persistence-enabling_kogito-configuring[_Enabling MongoDB persistence for {PRODUCT} services_]
* {URL_CONFIGURING_KOGITO}#proc-kafka-streams-persistence-enabling_kogito-configuring[_Enabling Kafka Streams persistence for {PRODUCT} services_]
* {URL_CONFIGURING_KOGITO}#proc-messaging-enabling_kogito-configuring[_Enabling messaging for {PRODUCT} services_]

{PRODUCT} Task Console::
A user interface for viewing and interacting with user tasks in {PRODUCT} process services.
+
[role="_additional-resources"]
.Additional resources
* {URL_PROCESS_SERVICES}#con-task-console_kogito-developing-process-services[_{PRODUCT} Task Console_]

{PRODUCT} Trusty Service::
A dedicated service in {PRODUCT} for storing all {PRODUCT} tracing events related to decisions made in {PRODUCT} services. The _{PRODUCT} Explainability Service_ is typically used in conjunction with this service.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#con-trusty-service_kogito-configuring[_{PRODUCT} Trusty Service and Explainability Service_]

message event::
A specified point in a business process where a defined message is used as the input (received) or output (sent) as a result of the process execution. For example, a message event might be an email sent to a specified user after a task is complete.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#con-kogito-runtime-events_kogito-configuring[_{PRODUCT} runtime events_]
* {URL_CONFIGURING_KOGITO}#proc-messaging-enabling_kogito-configuring[_Enabling messaging for {PRODUCT} services_]

MicroProfile Reactive Messaging::
A specification for sending and receiving messages within and between microservices using message brokers. {PRODUCT} supports https://github.com/eclipse/microprofile-reactive-messaging[MicroProfile Reactive Messaging] for messaging in {PRODUCT} services, such as message events used as either input or output of business process execution.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#proc-messaging-enabling_kogito-configuring[_Enabling messaging for {PRODUCT} services_]

middleware infrastructure services::
The collection of supplemental services in {PRODUCT} that provide capabilities such as persistence, messaging, and security. Key middleware infrastructure services in {PRODUCT} include Infinispan persistence and Apache Kafka reactive messaging.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#proc-infinispan-persistence-enabling_kogito-configuring[_Enabling Infinispan persistence for {PRODUCT} services_]
* {URL_CONFIGURING_KOGITO}#proc-messaging-enabling_kogito-configuring[_Enabling messaging for {PRODUCT} services_]

process definition::
A model that defines the components, workflow, and functionality for a business process, such as a BPMN model.

process instance::
An occurrence of a pending, running, or completed business process, based on the process definition.

PROTO file (`.proto`)::
A data library used for marshalling Java objects in protobuf (https://developers.google.com/protocol-buffers/[protocol buffers]) format. {PRODUCT} runtime persistence and communication with Infinispan or MongoDB are handled through a protobuf schema and generated marshallers.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#con-persistence_kogito-configuring[_Persistence in {PRODUCT}_]

task lifecycle::
A mechanism that moves a user task or custom task (work item) across various phases, such as *Active* -> *Claim* -> *Complete*. {PRODUCT} provides standard lifecycle phases for user tasks and also supports custom lifecycles or lifecycle phases.
+
[role="_additional-resources"]
.Additional resources
* {URL_PROCESS_SERVICES}#con-task-lifecycle_kogito-developing-process-services[_Task lifecycle in {PRODUCT} processes_]

unit of work::
A component in {PRODUCT} that serves as the basis for {PRODUCT} runtime execution. Units of work capture all steps in a process and are used internally to move a process instance from one state to the next state. After all possible steps in a process are successfully executed, the final state is sent to the {PRODUCT} runtime as a runtime event. {PRODUCT} can then use these events to notify third parties about changes to the BPMN process instance and its data.
+
[role="_additional-resources"]
.Additional resources
* {URL_CONFIGURING_KOGITO}#con-kogito-runtime-events_kogito-configuring[_{PRODUCT} runtime events_]

////
//@comment: Excluding for now due to current lack of support in Kogito. Will add once settled. (Stetson 2 Apr 2020)
Work item::
A custom task, typically a custom service task, that you can reuse across multiple business processes.

Work item handler::
A Java object that contains the implementation logic for a custom task (work item).
////

[role="_additional-resources"]
== Additional resources
* {URL_DECISION_SERVICES}[_{DECISION_SERVICES}_]
* {URL_PROCESS_SERVICES}[_{PROCESS_SERVICES}_]
* {URL_CONFIGURING_KOGITO}[_{CONFIGURING_KOGITO}_]

ifdef::parent-context[:context: {parent-context}]
ifndef::parent-context[:!context:]