This section provides more detail deploying an application built using the Compact Architecture that uses the IBM BAMOE add-ons, that collocate add-on services (Data-Index, Data-Audit, Jobs Service, and User Tasks) in the runtime.

Enabling persistence for stateful Workflows

BAMOE process service and all the Workflow subsystems (Data-Index, Data-Audit, Jobs Service, and User Tasks) use JDBC to persist in relational databases.

All BAMOE components will rely on the default DataSource to establish the connection with the connection with the Data Base, so it is mandatory that the applications has a DataSource correctly configured following the platform (Quarkus) guidelines.

Configuring persistence for BAMOE requires a minimal set of dependencies and configurations in your application. The minimal set of dependencies are:

  • Quarkus Agroal: Quarkus DataSource Connection Pool with Security and Transaction support

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-agroal</artifactId>
</dependency>

  • Database Specific Quarkus JDBC Driver

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-jdbc-{{your-database-type}}</artifactId>
</dependency>

  • KIE JDBC Persistence Add-on for Quarkus: Enables persistence for the Workflow Engine with JDBC.

<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-persistence-jdbc</artifactId>
</dependency>
Note
 For full information about how to configure DataSources in Quarkus, check the Configure data sources in Quarkus guide.

Configuring persistence for PostgreSQL

To configure PostgreSQL persistence for your Business Service, in your pom.xml add the following dependencies:

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-agroal</artifactId>
</dependency>

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>

<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-persistence-jdbc</artifactId>
</dependency>

Configuration required in your application.properties:

# Application default Datasource - PostgreSQL
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=bamoe-user
quarkus.datasource.password=bamoe-pass
quarkus.datasource.jdbc.url=${QUARKUS_DATASOURCE_JDBC_URL:jdbc:postgresql://0.0.0.0:5432/bamoe-db}

# Enabling jdbc persistence
kogito.persistence.type=jdbc

Configuring persistence for Microsoft SQL Server

To configure Microsoft SQL Server persistence for your Business Service, in your pom.xml add the following dependencies:

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-agroal</artifactId>
</dependency>

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-jdbc-mssql</artifactId>
</dependency>

<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-persistence-jdbc</artifactId>
</dependency>

Configuration required in your application.properties:

# Application default Datasource - Microsoft SQL Server
quarkus.datasource.db-kind=mssql
quarkus.datasource.username=bamoe-user
quarkus.datasource.password=bamoe-pass
quarkus.datasource.jdbc.url=${QUARKUS_DATASOURCE_JDBC_URL:jdbc:sqlserver://0.0.0.0:1433;DatabaseName=bamoe-db;encrypt=true;trustServerCertificate=true;}

# Enabling jdbc persistence
kogito.persistence.type=jdbc
Note
 If your Business Service uses Microsoft SQL Server persistence in Quarkus Dev Mode and want to use the Database Dev Services, ensure to read the Dev Services for Databases guide and apply the required License Acceptance configuration as explained in the Proprietary Databases - License Acceptance topic.

BAMOE mappings for Microsoft SQL Server

Additionally, if the Business Service includes Data-Index or Jobs Service, it is also required to add the bamoe-mssql-mappings dependency to ensure the correct behaviour of those components. This module includes the necessary Hibernate ORM mappings to help remapping some of the JPA entities used in both components. The mappings contained are:

  • META-INF/bamoe-data-index-orm.xml: This file remaps some entities from the data-index component.

  • META-INF/bamoe-job-service-orm.xml: This file remaps some entities from the job-service component.

Those mappings can be configured by using the quarkus.hibernate-orm.mapping-files configuration, and each one should be added only if the associated component is present in the application dependencies.

To correctly configure the Hibernate mappings, in your application pom.xml add:

<dependency>
  <groupId>com.ibm.bamoe</groupId>
  <artifactId>bamoe-mssql-mappings</artifactId>
</dependency>

And in the application.properties:

quarkus.hibernate-orm.mapping-files=META-INF/bamoe-data-index-orm.xml,META-INF/bamoe-job-service-orm.xml

Transaction isolation settings for Microsoft SQL Server

In order to ensure BAMOE is working properly when configured with a Microsoft SQL Server database, the following settings need to be applied at the database level:

    ALTER DATABASE <DATABASE_NAME> SET ALLOW_SNAPSHOT_ISOLATION ON;
    ALTER DATABASE <DATABASE_NAME> SET READ_COMMITTED_SNAPSHOT ON;

These settings are required to prevent database deadlocks when resources in BAMOE are accessed concurrently.

Configuring persistence for Oracle

To configure Oracle persistence for your Business Service, in your pom.xml add the following dependencies:

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-agroal</artifactId>
</dependency>

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-jdbc-oracle</artifactId>
</dependency>

<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-persistence-jdbc</artifactId>
</dependency>

Configuration required in your application.properties:

# Application default Datasource - Oracle
quarkus.datasource.db-kind=oracle
quarkus.datasource.username=bamoe-user
quarkus.datasource.password=bamoe-pass
quarkus.datasource.jdbc.url=jdbc:oracle:thin:@//oracle:1521/FREEPDB1

# Enabling jdbc persistence
kogito.persistence.type=jdbc

BAMOE mappings for Oracle

Additionally, if the Business Service includes User Tasks or Jobs Service, you will need to add the bamoe-oracle-mappings dependency, which includes the Hibernate ORM mappings that remap some of the JPA entities used in both components and ensure the correct behaviour. The mappings contained are:

  • META-INF/bamoe-user-task-orm.xml: This file remaps some entities from the jbpm-usertask-storage-jpa component.

  • META-INF/bamoe-job-service-orm.xml: This file remaps some entities from the job-service component.

Those mappings can be configured by using the quarkus.hibernate-orm.mapping-files configuration, and each one should be added only if the associated component is present in the application dependencies.

To correctly configure the Hibernate mappings, in your application pom.xml add:

<dependency>
  <groupId>com.ibm.bamoe</groupId>
  <artifactId>bamoe-oracle-mappings</artifactId>
</dependency>

And in the application.properties:

quarkus.hibernate-orm.mapping-files=META-INF/bamoe-user-task-orm.xml,META-INF/bamoe-job-service-orm.xml

Configuring persistence for H2 (Development only)

In development environments, you can use H2 persistence for your Business Service, in your pom.xml add the following dependencies:

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-agroal</artifactId>
</dependency>

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-jdbc-h2</artifactId>
</dependency>

<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-persistence-jdbc</artifactId>
</dependency>

Configuration required in your application.properties:

# Application default Datasource - H2
quarkus.datasource.db-kind=h2
datasource.devservices.properties.NON_KEYWORDS=VALUE,KEY

# Enabling jdbc persistence
kogito.persistence.type=jdbc

Setting up the database for stateful Workflows in development

All stateful Workflows subsystems brought by BAMOE into your Business Service project come with KIE Flyway migrations, a sandboxed Flyway-based mechanism that automatically creates the database schema for you during startup. This is convenient in development environments and is not suitable for production database instances

To enable this feature, the kie.flyway.enabled property should be added in your project application.properties file, which is found in src/main/resources as follows:

kie.flyway.enabled=false # for production
%dev.kie.flyway.enabled=true

Your development database schema will be automatically created for you.

Note

For production environemnts, see Creating your database schema for stateful Workflows based on BAMOE Installation DDL scripts.

Transactional operations on Compact Architecture

All the operations performed by the Process API layer on the Compact Architecture are transactional. In detail, all the endpoints are now compliant with the ACID properties, namely that in case of failure during a transaction, the action is undone, and any applied change is rolled back to restore the consistent state that existed before the transactional operation started. This makes all the operations performed on the Compact Architecture reliable and safe. Transactions are enabled as default choice on Compact Architecture projects.

Note
 The event subsystem in the BAMOE workflow engine does not have transactional support (see the Known Limitations section)

It is possible to disable the default behavior and make the operation no longer transactional by configuring your project application.properties with one of the properties shown in the following table:

Property Description Type Default

kogito.transactionEnabled

Globally sets transactions as enabled for the entire application

Boolean

true

kogito.processes.transactionEnabled

Sets the transactions as enabled for the Process API layer, overriding global behavior

Boolean

true

kogito.usertasks.transactionEnabled

Sets the transactions as enabled for the new User Tasks API layer, overriding global behavior

Boolean

true

Multi-threaded access to a Business Service

In an environment with multi-threaded access to a Business Service the workflow engine needs to ensure proper state of the runtime data. If a process instance, or other entity, is accessed concurrently by multiple threads, it can lead to race conditions. Use optimistic locking to ensure that concurrent access of the same database entity (E.g., process instance) is correctly handled. You can enable optimistic locking using the following property in application.properties:

# Enable optimistic locking
kogito.persistence.optimistic.lock=true

  • With optimistic locking enabled, if a process instance is accessed concurrently by more than one thread, the workflow engine will throw an optimistic lock exception. This exception will then be handled by the fault-tolerance system and retried, ensuring data consistency at runtime. For more information on fault-tolerance settings see https://quarkus.io/guides/smallrye-fault-tolerance.

  • With optimistic locking disabled, data consistency cannot be guaranteed during concurrent access of the runtime data in the workflow engine.