### Start Application (Gradle)

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-gradle-plugin-test/README.md

Execute this command in a separate terminal to start the Kogito application. This command should be run after initiating the continuous build.

```bash
./gradlew bootRun
```

--------------------------------

### KIE Flyway Properties Configuration Example

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/flyway/README.md

Example of a `kie-flyway.properties` file used to configure module name and SQL script locations for different database types.

```properties
# Name that identifies the module
module.name=runtime-persistence

# Script locations for the current module
module.locations.h2=classpath:kie-flyway/db/persistence-jdbc/h2
module.locations.postgresql=classpath:kie-flyway/db/persistence-jdbc/postgresql
# Default sql locations if the application db type isn't none of the above (ej: oracle)
module.locations.default=classpath:kie-flyway/db/persistence-jdbc/ansi
```

--------------------------------

### Install SDKMAN

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/Develop_on_Mac.md

Installs SDKMAN, a tool for managing multiple SDK versions, including Java.

```bash
curl -s "https://get.sdkman.io" | bash
```

--------------------------------

### Compile and Run Kogito Application

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/springboot/archetype/src/main/resources/archetype-resources/README.md

Use this command to compile the project and start the Spring Boot application.

```bash
mvn clean package spring-boot:run
```

--------------------------------

### Postgres Configuration for Quarkus

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/persistence/jdbc/README.md

Example configuration for connecting to a PostgreSQL database when using Quarkus.

```properties
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=postgres
quarkus.datasource.password=changeme
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/kogito
```

--------------------------------

### Run Kogito Application with Gradle

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-gradle-plugin-test/README.md

Use this command to directly start the Kogito Spring-Boot application from the command line.

```bash
./gradlew clean bootRun
```

--------------------------------

### Install Homebrew

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/Develop_on_Mac.md

Installs Homebrew, a package manager for macOS, which is used here to install GraalVM.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

--------------------------------

### Clone and Build Kogito Runtimes

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/CONTRIBUTING.md

Clone the repository and perform a quick build and install using Maven. This command skips plugins for a faster build.

```bash
git clone https://github.com/kiegroup/kogito-runtimes.git
cd kogito-runtimes
./mvnw clean install -Dquickly
# Wait... success!
```

--------------------------------

### Postgres Configuration for Spring Boot

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/persistence/jdbc/README.md

Example configuration for connecting to a PostgreSQL database when using Spring Boot.

```properties
spring.datasource.username=kogito-user
spring.datasource.password=kogito-pass
spring.datasource.url=jdbc:postgresql://localhost:5432/kogito
```

--------------------------------

### Oracle Configuration for Quarkus

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/persistence/jdbc/README.md

Example configuration for connecting to an Oracle database when using Quarkus.

```properties
quarkus.datasource.db-kind=oracle
quarkus.datasource.username=kogito-user
quarkus.datasource.password=kogito-user
quarkus.datasource.jdbc.url=jdbc:oracle:thin:@localhost:1521:kogito
```

--------------------------------

### Paginate and Sort Process Instances

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

GraphQL query demonstrating pagination (limit and offset) and sorting by start date for process instances.

```graphql
{
  ProcessInstances(where: {state: {equal: ACTIVE}}, orderBy: {start: ASC}, pagination: {limit: 10, offset: 0}) {
    id
    processId
    processName
    start
    end
    state
  }
}
```

--------------------------------

### Install GraalVM via Homebrew

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/Develop_on_Mac.md

Installs a specific version of GraalVM using Homebrew. Ensure you replace (*current_graalvm_version*) with the supported version.

```bash
brew install --cask graalvm/tap/(*current_graalvm_version*)
```

--------------------------------

### Oracle Configuration for Spring Boot

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/persistence/jdbc/README.md

Example configuration for connecting to an Oracle database when using Spring Boot.

```properties
spring.datasource.username=workflow
spring.datasource.password=workflow
spring.datasource.url=jdbc:oracle:thin:@localhost:1521:kogito
```

--------------------------------

### Sort Process Instances by Start Date

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

GraphQL query to sort process instances by their start date in ascending order (ASC).

```graphql
{
  ProcessInstances(where: {state: {equal: ACTIVE}}, orderBy: {start: ASC}) {
    id
    processId
    processName
    start
    end
    state
  }
}
```

--------------------------------

### Define a Java Template with Placeholders

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-codegen-modules/GUIDELINES.adoc

Example of a simple Java template file with placeholders that can be replaced during code generation.

```java
public class $ClassName$ {
    public void $method$() {}
}
```

--------------------------------

### Component-Specific Methods for Different Actions

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/api/kogito-api-incubation-common/README.md

Illustrates that component developers can provide specialized methods for different actions, such as creating, starting, and aborting a process instance.

```java
   LocalProcessInstanceId lpid = svc.createProcess(processId, inputDataContext);
   DataContext started = svc.start(lpid);
   DataContext aborted = svc.abort(lpid);

```

--------------------------------

### Run Kafka Docker Container

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Start a Kafka messaging server using the provided Docker image. This command exposes Kafka and ZooKeeper ports for local development.

```bash
docker run -p 2181:2181 -p 9092:9092 --env ADVERTISED_HOST=localhost --env ADVERTISED_PORT=9092 spotify/kafka
   
```

--------------------------------

### Asynchronous Process Service Operations

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/api/kogito-api-incubation-common/README.md

Demonstrates chaining asynchronous operations for process management, starting with creating a process and then starting its execution. This pattern is suitable for long-running or complex processes.

```java
CompletableFuture<LocalProcessInstanceId> futureLpid = asyncSvc.createProcess(processId, inputDataContext);
CompletableFuture<DataContext> futureStarted = futureLpid.andThen(lpid -> asyncSvc.start(lpid));
...
```

--------------------------------

### Link GraalVM in SDKMAN

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/Develop_on_Mac.md

Links the manually installed GraalVM with SDKMAN for easier management. Replace (*current_graalvm_version*) with the actual version.

```bash
sdk install java (*current_graalvm_version*)-grl /Library/Java/JavaVirtualMachines/(*current_graalvm_version*)/Contents/Home
```

--------------------------------

### Manually Setup Generators

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-codegen-modules/README.md

Manually configure generators for specific source types like rules or processes by invoking `setupGenerator` on the ApplicationGenerator instance. This allows for explicit control over which generators are used.

```java
appGen.setupGenerator(RuleCodegen.ofPath(context, ruleSourceDirectory));
    
    appGen.setupGenerator(ProcessCodegen.ofPath(context, processSourceDirectory));
```

--------------------------------

### Set SDKMAN to Use GraalVM

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/Develop_on_Mac.md

Configures SDKMAN to use the installed GraalVM version for the current session. Replace (*current_graalvm_version*) with the actual version.

```bash
sdk use java (*current_graalvm_version*)-grl
```

--------------------------------

### Enable Security with Quarkus Profile

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Security

Start the Data Index Service with the 'keycloak' Quarkus profile to enable OIDC security. If this profile is not used, the OIDC extension remains disabled.

```bash
mvn clean compile quarkus:dev  -Dquarkus.profile=keycloak -Dkogito.protobuf.folder=/home/git/kogito-runtimes/data-index/data-index-service/src/test/resources -Dkogito.protobuf.watch=true
```

--------------------------------

### Spring Framework Specific Application Configuration Template

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-codegen-modules/GUIDELINES.adoc

An example of a Spring-specific template for application configuration, extending Kogito's StaticConfig. This template does not contain placeholders.

```java
@org.springframework.stereotype.Component
public class ApplicationConfig extends org.kie.kogito.StaticConfig {

    @org.springframework.beans.factory.annotation.Autowired
    public ApplicationConfig(
            Collection<org.kie.kogito.KogitoConfig> configs) {
        super($Addons$, configs);
    }
    ...
```

--------------------------------

### Configure Infinispan Endpoints

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Modify the Infinispan configuration to remove the security domain from endpoints for a simplified demo setup. Ensure the endpoints socket binding is correctly defined.

```xml
<endpoints socket-binding="default">
   
```

--------------------------------

### Infinispan Indexed Model Example

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Sample proto message definition annotated for Infinispan indexing using Hibernate Search annotations. '@Indexed' marks the message for indexing, and '@Field' marks attributes to be indexed.

```protobuf
/* @Indexed */
message ProcessInstanceMeta {
    /* @Field(store = Store.YES) */
    optional string id = 1;
}
```

--------------------------------

### Bootstrap Data Index Service with Proto Files

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Configure the Data Index service to load proto files from a specified folder on application startup. Set 'kogito.protobuf.watch=true' to enable live reloading of file changes.

```bash
mvn clean compile quarkus:dev -Dkogito.protobuf.folder=/home/git/kogito-runtimes/data-index/data-index-service/src/test/resources -Dkogito.protobuf.watch=true
```

--------------------------------

### Quick Build with Unit Tests

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/CONTRIBUTING.md

Perform basic formatting validation and run all unit tests using Maven. Use this command for quick checks before a full build.

```bash
./mvnw clean install -DquickTests
```

--------------------------------

### Test Sample Process with cURL

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/springboot/archetype/src/main/resources/archetype-resources/README.md

Execute this cURL command to send a POST request to the greetings endpoint and test the sample process. Expect 'Hello World' in the application console upon success.

```sh
curl -d '{}' -H "Content-Type: application/json" -X POST http://localhost:8080/greetings
```

--------------------------------

### Generate Kogito Spring Boot Project with Starters

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/springboot/archetype/README.md

Generate a Kogito Spring Boot project and include specific Kogito Starters by using the `starters` property. Provide a comma-separated list of desired starters.

```shell
mvn archetype:generate \
    -DarchetypeGroupId=org.kie.kogito \
    -DarchetypeArtifactId=kogito-spring-boot-archetype \
    -DarchetypeVersion=2.0.0-SNAPSHOT \
    -DgroupId=com.company \
    -DartifactId=sample-kogito \
    -Dstarters=decisions,rules,processes
```

--------------------------------

### Add jBPM with Drools Spring Boot Starter

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/springboot/starters/README.md

Use this starter for projects requiring all Business Automation engine capabilities: Decisions, Rules, Process, and Predictions.

```xml
<dependencies>
  <dependency>
    <groupId>org.jbpm</groupId>
    <artifactId>jbpm-with-drools-spring-boot-starter</artifactId>
  </dependency>
</dependencies>
```

--------------------------------

### Initialize KieFlyway with DataSource

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/flyway/README.md

Basic initialization of KieFlyway using a provided DataSource. This is the entry point for running migrations.

```java
import org.kie.flyway.initializer.KieFlywayInitializer;

...
        KieFlywayInitializer.builder()
                .withDatasource(dataSource)
                .build()
                .migrate();

```

--------------------------------

### Constructing Process Path

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/api/kogito-api-incubation-common/README.md

Shows how to construct a path to a process using the application root and ProcessIds class.

```java
appRoot.get(ProcessIds.class).get("my.process")

```

--------------------------------

### Evaluating a DMN Decision

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/api/kogito-api-incubation-common/README.md

Shows a specific example of evaluating a DMN decision using a DecisionIds class and an evaluate method.

```java
   LocalDecisionId decisionId = appRoot.get(DecisionIds.class).get(namespaceString, nameString);
   DataContext result = svc.evaluate(decisionId, dataContext);

```

--------------------------------

### Build Kogito Application with Gradle

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-gradle-plugin-test/README.md

Use this command to build a JAR artifact for the Kogito application.

```bash
./gradlew clean jar
```

--------------------------------

### Build Native Image with Maven

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/Develop_on_Mac.md

Executes the Maven build command with the native profile activated to create a native executable.

```bash
mvn clean package -Pnative
```

--------------------------------

### Kafka Client Usage in Tests

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-test-utils/README.md

Demonstrates how to instantiate and use KafkaClient in tests, either with Spring's dependency injection or manually with bootstrap server details.

```java
@Autowired
private KafkaTestClient kafkaClient;
```

```java
@ConfigProperty(name = KafkaQuarkusTestResource.KOGITO_KAFKA_PROPERTY)
private String kafkaBootstrapServers;

@Test
public void myTest() {
    KafkaClient kafkaClient = new KafkaClient(kafkaBootstrapServers);
    // ...
}
```

--------------------------------

### Add jBPM Spring Boot Starter

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/springboot/starters/README.md

Add jBPM engine support (BPMN) to your project by including this starter.

```xml
<dependencies>
  <dependency>
    <groupId>org.jbpm</groupId>
    <artifactId>jbpm-spring-boot-starter</artifactId>
  </dependency>
</dependencies>
```

--------------------------------

### Applying Annotations in Code Generation

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-codegen-modules/GUIDELINES.adoc

Example of using an annotator to apply framework-specific directives like component injection and named injections to template fields during code generation.

```java
    annotator.withApplicationComponent(template);
    
    template.findAll(FieldDeclaration.class,
                        fd -> isProcessField(fd)).forEach(fd -> annotator.withNamedInjection(fd, processId));
    template.findAll(FieldDeclaration.class,
                        fd -> isApplicationField(fd)).forEach(fd -> annotator.withInjection(fd));
```

--------------------------------

### Initialize ApplicationGenerator

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-codegen-modules/README.md

Instantiate the ApplicationGenerator with the provided KogitoBuildContext. This is the main entry point for the code generation process.

```java
ApplicationGenerator appGen =
        new ApplicationGenerator(context);
```

--------------------------------

### Filtering Process Instances

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Demonstrates how to filter process instances based on various criteria.

```APIDOC
## Filtering Process Instances

### Description
Allows filtering of process instances using the `where` argument with various operators.

### Method
GET (via GraphQL endpoint)

### Endpoint
`http://localhost:8180/graphql`

### Query Parameters
- **query** (String) - The GraphQL query string.

### Request Examples

#### Filter by State
```graphql
{
  ProcessInstances(where: {state: {equal: ACTIVE}}) {
    id
    processId
    processName
    start
    state
    variables
  }
}
```

#### Filter by ID
```graphql
{
  ProcessInstances(where: {id: {equal: "d43a56b6-fb11-4066-b689-d70386b9a375"}}) {
    id
    processId
    processName
    start
    state
    variables
  }
}
```

#### Combining AND and OR operators
```graphql
{
  ProcessInstances(where: {or: {state: {equal: ACTIVE}, rootProcessId: {isNull: false}}}) {
    id
    processId
    processName
    start
    end
    state
  }
}
```

```graphql
{
  ProcessInstances(where: {and: {processId: {equal: "travels"}}, or: {state: {equal: ACTIVE}, rootProcessId: {isNull: false}}}) {
    id
    processId
    processName
    start
    end
    state
  }
}
```

### Response
#### Success Response (200)
Returns a list of process instances matching the specified filter criteria.
```

--------------------------------

### Filter Domain Cache by Traveller First Name

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Filter the domain-specific cache to list Travels where the traveller's first name starts with 'Cri'. The 'like' operator is case-sensitive.

```graphql
{
  Travels(where: {traveller: {firstName: {like: "Cri*"}}}) {
    flight {
      flightNumber
      arrival
      departure
    }
    traveller {
      email
    }
  }
}
```

--------------------------------

### Granting View Role to Kogito Service Account

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/kubernetes/README.md

This RoleBinding grants the 'view' ClusterRole to a specific ServiceAccount, allowing the Kogito service to 'get' pods and services, which is required for the Kubernetes add-on to function.

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: my-kogito-service-view
roleRef:
  kind: ClusterRole
  apiGroup: rbac.authorization.k8s.io
  name: view
subjects:
  - kind: ServiceAccount
    name: my-kogito-service
```

--------------------------------

### Change Data Index Service Log Level

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Adjust the log level for the Data Index service by modifying command-line arguments. This example sets console and specific Kogito category logs to DEBUG.

```bash
java -Dquarkus.log.console.level=DEBUG -Dquarkus.log.category.\"org.kie.kogito\".min-level=DEBUG -Dquarkus.log.category.\"org.kie.kogito\".level=DEBUG -jar target/data-index-service-8.0.0-SNAPSHOT-runner.jar
```

--------------------------------

### Generate Kogito Spring Boot Project with Add-Ons

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/springboot/archetype/README.md

Generate a Kogito Spring Boot project and include specific Kogito Add-Ons by using the `addons` property. Provide a comma-separated list of desired add-ons, omitting the common suffixes.

```shell
mvn archetype:generate \
    -DarchetypeGroupId=org.kie.kogito \
    -DarchetypeArtifactId=kogito-spring-boot-archetype \
    -DarchetypeVersion=2.0.0-SNAPSHOT \
    -DgroupId=com.company \
    -DartifactId=sample-kogito \
    -Daddons=monitoring-prometheus,persistence-infinispan
```

--------------------------------

### Run Kogito Service in Dev Mode

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Use this command to compile and run the Quarkus-based Kogito service in development mode, enabling live code reloading.

```bash
mvn clean compile quarkus:dev
```

--------------------------------

### Inject and Use EndpointDiscovery in Kogito Service

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/quarkus/addons/kubernetes/README.md

Inject the `EndpointDiscovery` bean into your custom Kogito service to find service endpoints by namespace and name. This example demonstrates how to query for an endpoint and handle cases where it's not found.

```java
import java.util.Optional;

import org.kie.kogito.addons.k8s.Endpoint;
import org.kie.kogito.addons.k8s.EndpointDiscovery;

@ApplicationScoped
public class EndpointFetcher {

    @Inject
    EndpointDiscovery endpointDiscovery;

    public void queryEndpoint(String namespace, String name) {
        final Optional<Endpoint> endpoint = endpointDiscovery.findEndpoint(namespace, name);
        if (endpoint.isEmpty()) {
            System.out.println("Endpoint not found :(");
        } else {
            System.out.println("This is the url for the service " + name + ": " + endpoint.get().getURL());
        }
    }
}
```

--------------------------------

### Initialize KieFlyway with DataSource, ClassLoader, and Exclusions

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/flyway/README.md

Advanced initialization of KieFlyway, allowing configuration of a custom ClassLoader and exclusion of specific modules.

```java
import org.kie.flyway.initializer.KieFlywayInitializer;

...
        KieFlywayInitializer.builder()
                .withDatasource(dataSource)
                .withClassLoader(this.getClass().getClassLoader())
                .withModuleExclusions(List.of("data-index", "jobs-service"))
                .build()
                .migrate();

```

--------------------------------

### Configure KIE Flyway Properties

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/flyway/README.md

Use these properties in `application.properties` to enable KIE Flyway and exclude specific modules from initialization.

```properties
...

# KIE Flyway setup
kie.flyway.enabled=true
kie.flyway.modules."data-index".enabled=false
kie.flyway.modules."jobs-service".enabled=false

```

--------------------------------

### Accessing a DMN Decision Service

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/api/kogito-api-incubation-common/README.md

Demonstrates how to construct a path to a DMN decision service, which is a subcomponent of a decision, using a fluent API.

```java
   LocalDecisionId decisionServiceId = appRoot.get(DecisionIds.class).get(namespaceString, nameString).services().get(serviceString);
   DataContext result = svc.evaluate(decisionServiceId, dataContext);

```

--------------------------------

### Add Deployment Module Dependencies

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/quarkus/extensions/README.md

Specify necessary dependencies in the deployment module's `pom.xml`, including `kogito-quarkus-common-deployment` and the specific Kogito extension artifact.

```xml
<dependency>
      <groupId>org.kie.kogito</groupId>
      <artifactId>kogito-quarkus-common-deployment</artifactId>
      <version>${project.version}</version>
    </dependency>

    <dependency>
      <groupId>org.kie.kogito</groupId>
      <artifactId>kogito-*</artifactId>
    </dependency>
```

--------------------------------

### Pagination for Domain Cache

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Details how to implement pagination for domain cache queries using `limit` and `offset` parameters, combined with filtering.

```APIDOC
## Pagination for Domain Cache

### Description
This operation demonstrates how to paginate through the domain cache results. You can control the number of results returned and the starting point of the results using `limit` and `offset` parameters, often in conjunction with filtering.

### GraphQL Query
```graphql
{
  Travels(where: {traveller: {firstName: {like: "Cri*"}}}, pagination: {offset: 0, limit: 10}) {
    flight {
      flightNumber
      arrival
      departure
    }
    traveller {
      email
    }
  }
}
```
```

--------------------------------

### Add Drools Decisions Spring Boot Starter

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/springboot/starters/README.md

Include this starter for Decision (DMN) support in your Kogito Spring Boot project.

```xml
<dependencies>
  <dependency>
    <groupId>org.drools</groupId>
    <artifactId>drools-decisions-spring-boot-starter</artifactId>
  </dependency>
</dependencies>
```

--------------------------------

### Sorting and Pagination

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Explains how to sort and paginate results for process and task instances.

```APIDOC
## Sorting and Pagination

### Description
Enables sorting of results using the `orderBy` parameter and pagination using the `pagination` parameter.

### Method
GET (via GraphQL endpoint)

### Endpoint
`http://localhost:8180/graphql`

### Query Parameters
- **query** (String) - The GraphQL query string.

### Request Examples

#### Sorting Process Instances
```graphql
{
  ProcessInstances(where: {state: {equal: ACTIVE}}, orderBy: {start: ASC}) {
    id
    processId
    processName
    start
    end
    state
  }
}
```

#### Pagination Process Instances
```graphql
{
  ProcessInstances(where: {state: {equal: ACTIVE}}, orderBy: {start: ASC}, pagination: {limit: 10, offset: 0}) {
    id
    processId
    processName
    start
    end
    state
  }
}
```

#### Sorting Multiple User Task Instances Attributes
```graphql
{
  UserTaskInstances(where: {state: {equal: "Ready"}}, orderBy: {name: ASC, actualOwner: DESC}) {
    id
    name
    actualOwner
    description
    priority
    processId
    processInstanceId
  }
}
```

### Response
#### Success Response (200)
Returns a list of process or task instances, sorted and paginated according to the specified parameters.
```

--------------------------------

### Format Copyright Headers

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/CONTRIBUTING.md

Run this Maven command to automatically format copyright headers in your files. Ensure your IDE is configured with the project's codestyle.

```bash
mvn com.mycila:license-maven-plugin:format
```

--------------------------------

### Query Process Instances

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Retrieve a list of all process instances. This query can be extended with filtering, sorting, and pagination.

```APIDOC
## Query Process Instances

### Description
Retrieves a list of process instances. Supports filtering, sorting, and pagination.

### Method
GET (via GraphQL endpoint)

### Endpoint
`http://localhost:8180/graphql`

### Query Parameters
- **query** (String) - The GraphQL query string.

### Request Example
```graphql
{
  ProcessInstances {
    id
    processId
    state
    parentProcessInstanceId
    rootProcessId
    rootProcessInstanceId
    variables
    nodes {
      id
      name
      type
    }
  }
}
```

### Response
#### Success Response (200)
- **ProcessInstances** (Array of Objects) - Contains details of process instances.
  - **id** (String)
  - **processId** (String)
  - **state** (String)
  - **parentProcessInstanceId** (String)
  - **rootProcessId** (String)
  - **rootProcessInstanceId** (String)
  - **variables** (Object)
  - **nodes** (Array of Objects)
    - **id** (String)
    - **name** (String)
    - **type** (String)

#### Response Example
```json
{
  "data": {
    "ProcessInstances": [
      {
        "id": "some-instance-id",
        "processId": "some-process-id",
        "state": "ACTIVE",
        "parentProcessInstanceId": null,
        "rootProcessId": "some-root-process-id",
        "rootProcessInstanceId": "some-root-instance-id",
        "variables": {},
        "nodes": []
      }
    ]
  }
}
```
```

--------------------------------

### Configure OIDC Security in application.properties

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Security

Configure OpenID Connect settings for the 'keycloak' profile in `application.properties`. This includes enabling OIDC, setting the authorization server URL, client ID, client secret, and defining role-based access policies for specific paths like '/graphql'.

```properties
%keycloak.quarkus.oidc.enabled=true
%keycloak.quarkus.oidc.auth-server-url=http://localhost:8280/auth/realms/kogito
%keycloak.quarkus.oidc.client-id=kogito-data-index-service
%keycloak.quarkus.oidc.credentials.secret=secret
%keycloak.quarkus.http.auth.policy.role-policy1.roles-allowed=confidential
%keycloak.quarkus.http.auth.permission.roles1.paths=/graphql
%keycloak.quarkus.http.auth.permission.roles1.policy=role-policy1
```

--------------------------------

### Generate Basic Kogito Spring Boot Project

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/springboot/archetype/README.md

Use this command to generate a new Kogito project with Spring Boot runtime. Specify the archetype group ID, artifact ID, version, and your project's group ID and artifact ID.

```shell
mvn archetype:generate \
    -DarchetypeGroupId=org.kie.kogito \
    -DarchetypeArtifactId=kogito-spring-boot-archetype \
    -DarchetypeVersion=2.0.0-SNAPSHOT \
    -DgroupId=com.company \
    -DartifactId=sample-kogito
```

--------------------------------

### Constructing Prediction Path

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/api/kogito-api-incubation-common/README.md

Demonstrates constructing a path to a prediction using the application root and PredictionIds class.

```java
appRoot.get(PredictionIds.class).get("my.prediction")

```

--------------------------------

### Generate and Modify Class using TemplatedGenerator

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-codegen-modules/GUIDELINES.adoc

Demonstrates how to load a template, parse it into an AST using JavaParser, and replace placeholders. It also shows how to set a fallback context for template resolution.

```java
CompilationUnit u = TemplatedGenerator.builder()
        .withFallbackContext(JavaKogitoBuildContext.CONTEXT_NAME)
        .build(context, "MyClass")
        .compilationUnitOrThrow("Impossible to find template");

u.findAll(
    ClassOrInterfaceDeclaration.class, 
        c -> c.getNameAsString().equals("$ClassName$"))
    .forEach(c-> c.setName("MyCustomName"));

u.findAll(
    MethodDeclaration.class, 
        c -> c.getNameAsString().equals("$method$"))
    .forEach(c-> c.setName("myMethodName"));
```

--------------------------------

### Constructing DMN Service Path

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/api/kogito-api-incubation-common/README.md

Illustrates the fluent API for constructing a path to a DMN decision service, reflecting the path structure /decisions/$id/services/$serviceId.

```java
appRoot.get(DecisionIds.class).get(namespace, name).services().get(serviceId)

```

--------------------------------

### Querying with Metadata

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Shows how to query the domain cache and include metadata, such as `lastUpdate`, `userTasks`, and `processInstances`, for correlation and filtering.

```APIDOC
## Querying with Metadata

### Description
This operation demonstrates how to retrieve data from the domain cache along with associated metadata. The `_metadata` attribute allows access to information like `lastUpdate`, `userTasks`, and `processInstances`.

### GraphQL Query
```graphql
{
  Travels {
    flight {
      flightNumber
      arrival
      departure
    }
    metadata {
      lastUpdate
      userTasks {
        name
      }
      processInstances {
        processId
      }
    }
  }
}
```
```

--------------------------------

### Filtering User Task Instances

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Demonstrates how to filter user task instances based on various criteria.

```APIDOC
## Filtering User Task Instances

### Description
Allows filtering of user task instances using the `where` argument with various operators.

### Method
GET (via GraphQL endpoint)

### Endpoint
`http://localhost:8180/graphql`

### Query Parameters
- **query** (String) - The GraphQL query string.

### Request Example
```graphql
{
  UserTaskInstances(where: {state: {equal: "Ready"}}) {
    id
    name
    actualOwner
    description
    priority
    processId
    processInstanceId
  }
}
```

### Response
#### Success Response (200)
Returns a list of user task instances matching the specified filter criteria.
```

--------------------------------

### Configure Infinispan Cache Template

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Add a basic template for the indexing cache in Infinispan. This configuration enables indexing for all fields and specifies a local-heap directory provider.

```xml
<local-cache-configuration name="kogito-template" statistics="true">
         <indexing index="ALL">
            <property name="default.directory_provider">local-heap</property>
         </indexing>
   </local-cache-configuration>
   
```

--------------------------------

### Generated Application Class

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-codegen-modules/README.md

The main entry point for a generated Kogito application, extending `StaticApplication` and loading engines like Processes and RuleUnits.

```java
package org.kie.kogito.app;

public class Application extends org.kie.kogito.StaticApplication {

  public Application() {
    super(new ApplicationConfig());
    loadEngines(new Processes(), new RuleUnits());
  }
}
```

--------------------------------

### Add Kogito Add-on Dependency to pom.xml

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/README.md

To use a Kogito Add-on, add its dependency to your project's pom.xml file. Replace `${kogito.version}` with the desired version.

```xml
<dependencies>
  <dependency>
    <groupId>org.kie</groupId>
    <artifactId>kie-addons-quarkus-process-management</artifactId>
    <version>${kogito.version}</version>
  </dependency>
</dependencies>
```

--------------------------------

### Add Kogito Predictions Spring Boot Starter

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/springboot/starters/README.md

Integrate Predictions (PMML) into your Kogito Spring Boot application by adding this starter.

```xml
<dependencies>
  <dependency>
    <groupId>org.kie</groupId>
    <artifactId>kie-predictions-spring-boot-starter</artifactId>
  </dependency>
</dependencies>
```

--------------------------------

### Mixed Dependency Injection in Kogito Process

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-codegen-modules/GUIDELINES.adoc

Demonstrates the mixed usage of field and constructor injection in a Kogito process class. Constructor injection is preferred for most dependencies, while field injection is used for REST endpoints and specific cases.

```java
@org.springframework.stereotype.Component("Travelers")
public class TravelersProcess extends AbstractProcess<TravelersModel> {

    // field injection
    @org.springframework.beans.factory.annotation.Autowired(required = false)
    Collection<WorkItemHandler> handlers;

    Application app;

    // field injection
    @org.springframework.beans.factory.annotation.Autowired()
    org.kie.kogito.test.TravelersMessageProducer_7 producer_7;

    // constructor injection
    @org.springframework.beans.factory.annotation.Autowired()
    public TravelersProcess(org.kie.kogito.app.Application app) {
        super(app.config().get(org.kie.kogito.process.ProcessConfig.class));
        this.app = app;
    }

    // post construct method that delegates to a non-final 
    // super-class method
    @jakarta.annotation.PostConstruct()
    public void init() {
        this.activate();
    }
}
```

--------------------------------

### Configure Plugin Management with Maven Repository

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-gradle-plugin/README.md

Declare the plugin management in your settings.gradle.kts file, specifying the Maven repository location for the plugin.

```kotlin
pluginManagement {
  repositories {
    maven {
      val repoLocation = ...
      url = uri(repoLocation)
    }
  }
  resolutionStrategy {
    eachPlugin {
      if (requested.id.namespace == "org.kie.kogito.gradle") {
        useModule("org.kie.kogito:kogito-gradle-plugin:${requested.version}")
      }
    }
  }
}
```

--------------------------------

### Enable JDBC Persistence

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/persistence/jdbc/README.md

Set this property to enable JDBC persistence for Kogito.

```properties
kogito.persistence.type=jdbc
```

--------------------------------

### Apply Kogito Gradle Plugin

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-gradle-plugin/README.md

Apply the Kogito Gradle plugin in your build.gradle.kts file using its ID and version.

```kotlin
plugins {
  id("org.kie.kogito.gradle") version "..." (the current kogito version)
}
```

--------------------------------

### Watch for Code Changes and Rebuild (Gradle Continuous Build)

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-gradle-plugin-test/README.md

Execute this command in one terminal to continuously monitor source files for changes and trigger recompilation and rebuilding of the application.

```bash
./gradlew clean compileSecondaryJava --continuous --parallel --build-cache
```

--------------------------------

### Query All Process Instances

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

GraphQL query to retrieve all process instances, including their ID, process ID, state, parent and root instance IDs, variables, and associated nodes.

```graphql
{
  ProcessInstances {
    id
    processId
    state
    parentProcessInstanceId
    rootProcessId
    rootProcessInstanceId
    variables
    nodes {
      id
      name
      type
    }
  }
}
```

--------------------------------

### Add Quarkus Plugins to Runtime Module POM

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/quarkus/extensions/README.md

Configure the `pom.xml` in the runtime module of a Kogito extension to include Quarkus build plugins, specifically the `quarkus-bootstrap-maven-plugin` for extension descriptor generation.

```xml
<build>
    <plugins>
      <plugin>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-bootstrap-maven-plugin</artifactId>
        <configuration>
          <annotationProcessorPaths>
            <path>
              <groupId>io.quarkus</groupId>
              <artifactId>quarkus-extension-processor</artifactId>
              <version>${version.io.quarkus}</version>
            </path>
          </annotationProcessorPaths>
        </configuration>
        <executions>
          <execution>
            <goals>
              <goal>extension-descriptor</goal>
            </goals>
            <phase>compile</phase>
            <configuration>
              <deployment>${project.groupId}:${project.artifactId}-deployment:${project.version}
              </deployment>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
```

--------------------------------

### Execute Data Index Service Runner Jar

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Execute the generated uber jar for the Data Index service.

```bash
java -jar target/data-index-service-8.0.0-SNAPSHOT-runner.jar
```

--------------------------------

### General Service Interaction Pattern

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/api/kogito-api-incubation-common/README.md

Illustrates the generic pattern for interacting with services, involving obtaining an identifier and then calling an evaluation method with a DataContext.

```java
   LocalId id = appRoot.get(MyComponent.class).get("componentName").subs().get("someSubComponent")
   DataContext result = svc.evaluationMethod(id, dataContext);

```

--------------------------------

### Query User Task Instances

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Retrieve a list of user task instances. This query can be extended with filtering, sorting, and pagination.

```APIDOC
## Query User Task Instances

### Description
Retrieves a list of user task instances. Supports filtering, sorting, and pagination.

### Method
GET (via GraphQL endpoint)

### Endpoint
`http://localhost:8180/graphql`

### Query Parameters
- **query** (String) - The GraphQL query string.

### Request Example
```graphql
{
  UserTaskInstances {
    id
    name
    actualOwner
    description
    priority
    processId
    processInstanceId
  }
}
```

### Response
#### Success Response (200)
- **UserTaskInstances** (Array of Objects) - Contains details of user task instances.
  - **id** (String)
  - **name** (String)
  - **actualOwner** (String)
  - **description** (String)
  - **priority** (Integer)
  - **processId** (String)
  - **processInstanceId** (String)

#### Response Example
```json
{
  "data": {
    "UserTaskInstances": [
      {
        "id": "some-task-id",
        "name": "Some Task Name",
        "actualOwner": "john.doe@example.com",
        "description": "A task for user approval",
        "priority": 1,
        "processId": "some-process-id",
        "processInstanceId": "some-instance-id"
      }
    ]
  }
}
```
```

--------------------------------

### Add Runtime Module Dependency

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/quarkus/extensions/README.md

Include the `kogito-quarkus-common` dependency in the runtime module's `pom.xml` to leverage shared common runtime code for Kogito Quarkus extensions.

```xml
<dependency>
      <groupId>org.kie.kogito</groupId>
      <artifactId>kogito-quarkus-common</artifactId>
    </dependency>
```

--------------------------------

### Injecting Engines into Custom Beans

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-codegen-modules/README.md

Demonstrates how to inject Kogito engines like `Processes` and `DecisionModels` directly into custom beans within Spring or Quarkus applications.

```java
package org.my.package;

@ApplicationScoped
public class MyCustomBean {
  
  @Inject
  private Processes processes;

  @Inject
  private DecisionModels decisionModels;
  
  ...
}
```

--------------------------------

### Migrate All Process Instances

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/process-instance-migration/README.md

Use this endpoint to migrate all active process instances of a given process ID to a new target process and version. The request body specifies the target process ID and version.

```json
{
"targetProcessId": "<>",
"targetProcessVersion": "<>"
}
```

--------------------------------

### Querying the Domain Cache

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

Demonstrates how to query the domain cache for specific data, such as visa application details, flight information, hotel details, and traveler information.

```APIDOC
## Querying the Domain Cache

### Description
This operation allows you to retrieve data from the domain cache. You can select specific fields from various entities like `visaApplication`, `flight`, `hotel`, and `traveller`.

### GraphQL Query
```graphql
{
  Travels {
    visaApplication {
      duration
    }
    flight {
      flightNumber
      gate
    }
    hotel {
      name
      address {
        city
        country
      }
    }
    traveller {
      firstName
      lastName
      nationality
      email
    }
  }
}
```
```

--------------------------------

### Create JUnit Test Scenario Activator

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/drools/kogito-scenario-simulation/README.md

Create this Java file to activate the execution of Test Scenario files (*.scesim) using a custom JUnit runner. This class will discover and run all scesim files in the project.

```java
package testscenario;

import org.drools.scenariosimulation.backend.runner.TestScenarioActivator;

/**
 * KogitoJunitActivator is a custom JUnit runner that enables the execution of Test Scenario files (*.scesim).
 * This activator class, when executed, will load all scesim files available in the project and run them.
 * Each row of the scenario will generate a test JUnit result.
 */
@TestScenarioActivator
public class TestScenarioJunitActivatorTest {
}
```

--------------------------------

### Query All User Task Instances

Source: https://github.com/apache/incubator-kie-kogito-runtimes/wiki/Data-Index-Service

GraphQL query to retrieve all user task instances, including their ID, name, actual owner, description, priority, process ID, and process instance ID.

```graphql
{
  UserTaskInstances {
    id
    name
    actualOwner
    description
    priority
    processId
    processInstanceId
  }
}
```

--------------------------------

### Kubernetes Client Configuration Properties

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/springboot/addons/kubernetes/README.md

Set these properties in your test environment to ensure the correct KubernetesClient bean is created. This guarantees proper integration with the Kubernetes API.

```properties
spring.main.cloud-platform=KUBERNETES
spring.cloud.bootstrap.enabled=true
```

--------------------------------

### Migrate All Process Instances

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/addons/common/process-instance-migration/README.md

Migrates all active process instances of a given source process ID to a new target process ID and version.

```APIDOC
## Migrate All Process Instances

### Description
Migrates all active process instances of a given source process ID to a new target process ID and version.

### Method
POST

### Endpoint
/management/processes/{processId}/migrate

### Parameters
#### Path Parameters
- **processId** (string) - Required - The identifier of the source process.

#### Request Body
- **targetProcessId** (string) - Required - The identifier of the target process.
- **targetProcessVersion** (string) - Required - The version of the target process.

### Response
#### Success Response (200)
- **message** (string) - A message indicating the status of the migration.
- **numberOfProcessInstanceMigrated** (integer) - The number of process instances that were migrated.

#### Response Example
```json
{
  "message": "All instances migrated",
  "numberOfProcessInstanceMigrated": 1
}
```
```

--------------------------------

### Import Kogito Spring Boot BOM in Maven Project

Source: https://github.com/apache/incubator-kie-kogito-runtimes/blob/main/kogito-build/README.md

Use this snippet to import the Kogito Spring Boot BOM, aligning Kogito libraries with Spring Boot dependencies for Spring Boot runtimes.

```xml
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.kie.kogito</groupId>
      <artifactId>kogito-spring-boot-bom</artifactId>
      <version>${kogito.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
```