You can create a Business Service using the Workflow engines with the Spring Boot framework support.

During the compilation, some code is automatically generated by a specific Maven plugin where part of the code is common and the rest of it is engine-specific.

For each model, REST endpoints are generated, that are specific to the model and the engine.

You can add custom classes to the Business Service project to provide additional functionality, which is built with the automatically generated code as in normal Java applications.

Dependencies

Use the Spring Boot BOM to facilitate management of all BAMOE libraries.

Add the com.ibm.bamoe:bamoe-spring-boot-bom dependency to the <dependencyManagement> section of your project POM. You can then add the dependencies you require from those available in the BOM POMs using the <dependency> tags. For more information, see BAMOE Bill of Materials (BOM).

The org.springframework.boot:spring-boot-starter-actuator and org.jbpm:jbpm-with-drools-spring-boot-starter dependencies are required for a workflow Business Service project built with Spring Boot. For more information, see Workflows (Spring Boot).

To correctly build and package the application, use org.kie.kogito:kogito-maven-plugin and the org.springframework.boot:spring-boot-maven-plugin Maven plugins. For more information, see org.kie.kogito:kogito-maven-plugin and org.springframework.boot:spring-boot-maven-plugin external documentation.

For org.kie.kogito:kogito-maven-plugin dependency, see Decisions, Rules, and Decision Tables (Spring Boot).

Workflow subsystem add-ons (Spring Boot)

The following Spring Boot add-ons provide extensions for enabling persistence, embedded subsystem execution, and integration with workflow-related components such as Data Index, Data Audit, Jobs Service, and User Tasks.

Data-Index add-on

Use to enable the workflow runtime to persist data directly into the Data-Index subsystem. For more information, see Workflows (Stateful) subsystem → Data-Index.

  • org.kie:kogito-addons-springboot-data-index-jpa

The following add-ons require JDBC driver configuration when persistence layers are involved. For more information, see Enabling persistence for stateful Workflows.

Data-Audit add-ons

Use to enable Data-Audit integration with the Business Service. For more information, see Workflows (Stateful) subsystem → Data-Audit.

  • org.kie:kogito-addons-springboot-data-audit

  • org.kie:kogito-addons-springboot-data-audit-jpa

Embedded Jobs Service add-ons

Use to enable the colocation of the Jobs Service within the workflow runtime. For more information, see Workflows (Stateful) subsystem → Jobs Service.

  • org.kie:kogito-addons-springboot-embedded-jobs

  • org.kie:kogito-addons-springboot-embedded-jobs-jpa

User Tasks add-on

Use database-backed storage to enable the User Tasks subsystem to persist its data instead of relying on the default in‑memory storage. For more information, see Workflows (Stateful) subsystem → User Tasks.

  • org.jbpm:jbpm-addons-springboot-usertask-storage-jpa

With a stateful Workflow you will often combine events and messages in your Workflows, see Using Events in Workflows for more details on implementing Events and Messaging within Workflows.

Depending on your Business Services with workflow(s) use case many add-ons are available to be configured as required, see Reference → BAMOE Maven repository libraries for a complete list.

See the complete POM for workflows with Spring Boot for a Business Service with stateful workflow on Spring Boot.

Beside the POM file, the application.properties file is required to further customize the application with Spring Boot or BAMOE specific properties (for example, server.address).

Enabling persistence for stateful Workflows

BAMOE Business Services containing workflow(s) and all the Workflow subsystems (Data-Index, Data-Audit, Jobs Service, and User Tasks) use JDBC to persist in relational databases.

All BAMOE components rely on the default DataSource to establish the connection with the Database. Therefore it is important that the application has a DataSource correctly configured according to the Spring Boot platform guidelines.

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

org.kie:kie-addons-springboot-persistence-jdbc

KIE JDBC Persistence Add-on for Springboot see Workflows Stateful persistence.

Note
 For full information about how to configure DataSources in Spring Boot, check the Data Access guide.

Configuring persistence for PostgreSQL

To configure PostgreSQL persistence for your Business Service, in your POM file add the following dependencies:

  • org.postgresql:postgresql

  • org.flywaydb:flyway-database-postgresql if you use flyway

Add the following configuration properties required in your application.properties:

spring.datasource.url=jdbc:postgresql://0.0.0.0:5432/bamoe-db
spring.datasource.username=kogito-user
spring.datasource.password=kogito-pass

#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 file add the following dependencies:

  • com.microsoft.sqlserver:mssql-jdbc

  • org.flywaydb:flyway-sqlserver if you use flyway.

Add the following configuration properties required in your application.properties:

spring.datasource.url=jdbc:sqlserver://mssql-host:1433;databaseName=bamoe-db;encrypt=true;trustServerCertificate=true
spring.datasource.username=sa
spring.datasource.password=Pass@123

#Enabling jdbc persistence
kogito.persistence.type=jdbc

BAMOE mappings for Microsoft SQL Server

Additionally, if the Business Service includes Data-Index or Jobs Service, you must add the com.ibm.bamoe:bamoe-mssql-mappings dependency to ensure the correct behavior of those components.

This module includes the necessary Hibernate ORM mappings to support remapping some JPA entities used in both components. The mappings contained are:

META-INF/bamoe-data-index-orm.xml

File remaps several entities from the data-index component.

META-INF/bamoe-job-service-orm.xml

File remaps several entities from the job-service component.

com.ibm.bamoe:bamoe-mssql-mappings

Required database-specific mappings to ensure persistence layer works correctly with that database’s dialect and limitations.

Add com.ibm.bamoe:bamoe-mssql-mappings dependency in your application POM to correctly configure the Hibernate mappings. For the dependency, see Workflows Stateful persistence.

Add the following configuration property required in your application.properties:

spring.jpa.mapping-resources=META-INF/bamoe-data-index-orm.xml,META-INF/bamoe-job-service-orm.xml

Transaction isolation settings for Microsoft SQL Server

To ensure BAMOE works properly when configured with a Microsoft SQL Server database and to prevent deadlocks under load, you must enable snapshot isolation at both the database and application levels.

At the database level, enable snapshot isolation and row versioning by running the following SQL commands:

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

At the application level, configure the transaction isolation level at the connection level by adding the following property:

spring.datasource.hikari.connection-init-sql=SET TRANSACTION ISOLATION LEVEL SNAPSHOT
Note
 This property requires the database schema to be set up manually with the configuration property kie.flyway.enabled set to false.

Configuring persistence for Oracle

To configure Oracle persistence for your Business Service, in your POM add the following dependencies:

  • com.oracle.database.jdbc:ojdbc11

  • org.flywaydb:flyway-database-oracle if you use flyway

Add the following configuration properties required in your application.properties:

spring.datasource.url=jdbc:oracle:thin:@//oracle:1521/FREEPDB1
spring.datasource.username=system
spring.datasource.password=Password123456

#Enabling jdbc persistence
kogito.persistence.type=jdbc

BAMOE mappings for Oracle

Additionally, if the Business Service includes User Tasks or Jobs Service, you must add the com.ibm.bamoe: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 behavior. The mappings contained are:

META-INF/bamoe-user-task-orm.xml

File remaps several entities from the jbpm-usertask-storage-jpa component.

META-INF/bamoe-job-service-orm.xml

File remaps several entities from the job-service component.

com.ibm.bamoe:bamoe-oracle-mappings

Required database-specific mappings to ensure persistence layer works correctly with that database’s dialect and limitations.

Add com.ibm.bamoe:bamoe-oracle-mappings dependency in your application POM to correctly configure the Hibernate mappings. For the dependency, see Workflows Stateful persistence.

Add the following configuration property required in your application.properties:

spring.jpa.mapping-resources=META-INF/bamoe-data-index-orm.xml,META-INF/bamoe-job-service-orm.xml

Configuring persistence for Db2

To configure Db2 persistence for your Business Service, in your POM add the following dependencies:

  • com.ibm.db2:jcc

  • org.flywaydb:flyway-database-db2 if you use flyway

Add the following configuration properties required in your application.properties:

spring.datasource.url=jdbc:db2://host:port/testdb
spring.datasource.username=bamoe-user
spring.datasource.password=bamoe-pass
spring.datasource.driver-class-name=com.ibm.db2.jcc.DB2Driver

// Enabling jdbc persistence
kogito.persistence.type=jdbc

// Optional enable flyway for automated schema management
kie.flyway.enabled=true

Configuring persistence for H2 (Development only)

To configure H2 persistence for your Business Service in your POM file add the com.h2database:h2 dependency. The Flyway dependency is not required for H2.

Add the following configuration properties required in your application.properties:

spring.datasource.url=jdbc:h2:mem:bamoe;NON_KEYWORDS=VALUE,KEY
spring.datasource.username=bamoe
spring.datasource.password=bamoe

Code structure

A Workflow service built with Spring Boot includes the following key elements that define its structure, behavior, and runtime configuration:

Java domain models and business services

Located under src/main/java, these classes implement the domain model and any optional business services. Domain model classes define the structure of process data (e.g. CandidateData, Offer, or CreditCardDetails) that are passed between workflow steps. Optional business services may be invoked from Service Tasks in workflows.

Workflow definitions

One or more BPMN process models (.bpmn or .bpmn2) are placed under src/main/resources. These files describe the workflow logic, tasks, transitions, and overall process flow executed by the service.

Application and additional configuration

The src/main/resources directory also contains the application.properties file, used to configure Spring Boot and BAMOE features such as persistence, the embedded Job Service, and Data Index. Additional configuration files, such as calendars or custom properties, may also be included.

Testing resources

Under src/test/java, JUnit test classes validate workflow execution.

Testing workflow execution with BAMOE Spring Boot Web Console

The BAMOE Spring Boot Web Console is a web app that attaches to the Spring Boot application and allows developers to interact and manage running processes locally.

After you create a Business Service with the Spring Boot framework support, add the com.ibm.bamoe:bamoe-spring-boot-web-console BAMOE Spring Boot Web Console dependency to your POM file. For the dependency, see Workflows (Spring Boot dev + testing).

Update the application.properties file to add users and user groups in the following format:

bamoe.web-console.users.<username>.groups=<comma separated list of groups>.

For example:

bamoe.web-console.users.jdoe.groups=admin,HR,IT
bamoe.web-console.users.alice.groups=HR,IT
bamoe.web-console.users.admin.groups=admin

Add the following property in your application.properties file to enable the BAMOE Spring Boot Web Console:

bamoe.web-console.enabled=true

To include the Swagger UI with the Open API specifications for your Workflow, add the following properties:

.swagger-ui.always-include=true
.smallrye-openapi.path=docs/openapi.json

To install the dependencies and run your Spring Boot application in Dev mode locally, open a new terminal and execute one of the following commands:

mvn clean spring-boot:run -Pdevelopment
gradle clean bootRun
Note
 Maven places all build artifacts in the /target directory, while Gradle places them in the build/ directory.

Using the BAMOE Spring Boot Web Console interface to manage processes

To access the BAMOE Spring Boot Web Console, open a browser and navigate to http://localhost:8080/dev/bamoe-web-console/.

Process Instances

The Process Instances page displays all the running processes and their execution status. Click on any process instance to open the Process Instance details page.

BAMOE Spring Boot Web Console Process Instances page

Starting a new process instance

To start a new process instance, go to the Process Definitions tab. You will see a list of all the Process Definitions, one for each Workflow in your resources directory.

Click on any Process Definition to open its respective initialization form. Fill in the form with relevant data for your Workflow and click Start.

Process Definition form page
Note
 The Process Definitions forms are auto generated, but can be customized in the Forms page. See more in the Forms section.

Jobs

The Jobs page displays all the scheduled jobs and their execution status. Click on the actions menu on any job to show available options, including Details, which opens the job details modal.

Jobs page

Tasks

The Tasks page displays all the User Tasks and their priorities and status.

Tasks page

Click on the task name to open the User Task Form that can be filled and submitted to progress it to the next phase.

Task Form page

Click on View Details to open a side panel with more details on the current task, e.g., the parent process (if it exists), assigned users/groups, id, name, and state.

Task details panel
Note
 The Task forms are auto generated, but can be customized in the Forms page. See more in the Forms section.

Forms

The Forms page displays all the available forms in the project. It is initially empty, since all forms (for User Tasks and Process Definitions) are auto generated.

To add custom forms (for example, in the hiring Process Definition or HR Interview User Task), follow the steps in Form code generation functionality and then place the generated forms in the src/main/resources/custom-forms-dev folder.

Forms page

Process Instance Migration

If you have added the BAMOE Process Instance Migration (PIM) Add-on dependency to your Business Service you can access the same PIM User Interface that is integrated in the BAMOE Management Console, to be able to manage the migration of in-flight Process Instances to updated Process Definitions, see Managing live Workflows using BAMOE Management Console

Using the Swagger UI

Although the Swagger UI is not directly related to the BAMOE Spring Boot Web Console, it is a useful tool to explore the REST and GraphQL API endpoints of your Workflow.

The Swagger UI lists all endpoints generated for your Workflow as well as the extra endpoints for management, such as /management/processes.

To use the API, select any endpoint and click on Try it out to test it.

Swagger UI page
Swagger UI try it out page

Using the Data-Index Graphql UI

Data-Index provides a GraphiQL UI that provides a graphic interface to run and test GraphQL queries against the Data-Index GraphQL API in your Business Service.

Data-Index GraphiQL UI

In Spring-Boot the GraphiQL UI can be configured with the following properties:

spring.graphql.graphiql.enabled

(true|false) Enables the GraphiQL UI

spring.graphql.graphiql.path

(text) Sets the path to access the GraphiQL UI. Defaults to /graphiql

To enable the GraphiQL UI, add the following properties in your application.properties file:

spring.graphql.graphiql.enabled=true
spring.graphql.graphiql.path=/graphiql

When enabled, to access the GraphiQL UI, in your browser navigate to http://localhost:8080/graphiql.