The BAMOE v8 to v9 migration tutorials are designed to help you upgrade your applications. Each tutorial walks you through real migration scenarios step by step, explaining what changes in v9 mean for your existing v8 projects. You can find practical examples, side-by-side v8 and v9 code, and solutions to common issues discovered during migrations.

These tutorials are actively maintained and updated based on customer feedback and new migration patterns discovered over time.

Repository structure

Tutorials are organized in the _code/v8-to-v9-migration-tutorials directory. Inside the repository, you can find the following elements:

  • A README.md file that serves as the primary repository documentation.

  • A TUTORIAL_TEMPLATE.md file used as a base format for creating new tutorials.

  • Thirteen tutorial folders, each following the same internal structure:

    • A README.md file containing the tutorial content and explanation.

    • A v8-app directory holding the original BAMOE v8 reference implementation.

    • A v9-app directory containing the migrated BAMOE v9 version.

      Each tutorial folder mirrors this pattern.

Tutorial List

Category Tutorial Name Directory Key Topics

Business Central Samples

Tutorial 1: Evaluation Process Migration

tutorial-01-evaluation-process

Migrating a simple approval workflow with user tasks, parallel gateways, and form generation using both CLI and UI migration approaches.

Tutorial 2: Mortgage Application Migration

tutorial-02-mortgage-application

Migrating DMN decision tables with DMN 1.6 compatibility and running test scenarios.

Tutorial 3: Traffic Violation (DMN) Migration

tutorial-03-traffic-violation

Migrating BPMN processes that use DRL rules, updating legacy ruleflow-group logic, and converting guided decision tables to DRL.

Upgrade Guide Scenarios

Tutorial 4: Upgrade Guide Scenarios

tutorial-04-upgrade-guide-scenarios

Addressing 11 common migration issues, including process ID rules, javax to jakarta updates, variable/context changes, Java type handling, and rule unit migration.

Event Listeners

Tutorial 5: Event Listeners Migration

tutorial-05-event-listeners

Migrating process, task, and rule event listeners to the new v9 APIs and registration methods.

Advanced Features

Tutorial 6: Process Variable Persistence

tutorial-06-process-variable-persistence

Migrating JPA entities to jakarta.persistence, replacing persistence.xml with Quarkus datasource settings, and configuring Hibernate ORM for variable persistence.

Tutorial 7: Human Task (Escalation & Reassignment)

tutorial-07-human-task-escalation

Migrating task deadlines, escalation rules, SLA triggers, and dynamic assignment strategies.

Tutorial 8: Email Notifications

tutorial-08-email-notifications

Migrating email notifications using work item handlers, template-based messages, and updated email configuration.

Custom Scenarios

Tutorial 9: Complex Data Models

tutorial-09-complex-data-models

Migrating complex JPA entity models with updated annotations, validation rules, and persistence troubleshooting.

Tutorial 10: Multi-Module Projects

tutorial-10-multi-module-projects

Migrating Maven multi-module structures, including parent POM setup, dependency management, and module communication.

Tutorial 11: External Services Integration & Security

tutorial-11-external-services-security

Migrating from UserGroupCallback to IdentityProvider, implementing UserTaskAssignmentStrategy, and integrating OIDC/JWT-based user task assignment.

Tutorial 12: Database Integration & Async Processing

tutorial-12-database-async-processing

Migrating database configuration from KIE Server properties to Quarkus datasource settings, adding Flyway schema management, and integrating Jobs Service for async tasks.

Common Issues & Solutions

Tutorial 13: Common Migration Issues and Solutions

tutorial-13-common-migration-issues

Complete reference for all common migration issues with detailed solutions, workarounds, root cause analysis, and guidance on when to contact support

Tutorial structure

Each tutorial follows a consistent format:

Introduction

Describes the migration target and explains the purpose and relevance of the scenario.

Prerequisites

Lists required tools, configurations, and prior knowledge needed before starting.

Step-by-Step Migration

Provides sequential instructions with necessary commands, code samples, and technical details.

Testing

Outlines the verification steps used to confirm a successful migration.

Common Issues

Summarizes frequent problems and provides troubleshooting guidance.

Summary

Recaps the completed tasks and highlights the key results.

How to use tutorials

  1. Begin with foundational content. If you are unfamiliar with migration workflows, start with Tutorial 1 (Evaluation Process).

  2. Select scenario-specific tutorials. Choose the tutorials that correspond to the features and components you use in the target application.

  3. Follow the procedures sequentially. Each tutorial is self-contained and provides a complete, ordered set of instructions.

  4. Validate progress continuously. Execute the test steps included in each tutorial before moving on to the next phase.

  5. Consult troubleshooting guidance. Refer to Tutorial 13 for common issues and recommended resolutions.

Getting started

Prerequisites

Before starting any tutorial, ensure you have:

  • BAMOE v9.x Maven repository configured in your settings.xml.

  • Java 17+, as required by BAMOE v9.

  • Maven 3.8.1+ installed.

  • Development environment is prepared using either BAMOE Canvas (web-based) or Visual Studio Code with the BAMOE Developer Tools extension.

  • Foundational knowledge of BPMN, DMN, or DRL (as applicable to the specific tutorial).

Note
 You do not need BAMOE v8 installed. The tutorials provide v8 application code in the repository for reference, and you’ll create new v9 applications using accelerators.

Creating BAMOE v9 Projects with Accelerators

All tutorials rely on the BAMOE Canvas Quarkus accelerator to generate BAMOE v9 projects. You can create your project in the following ways:

  • Clone the Accelerator Directly (Recommended).

  • Use BAMOE Canvas Web Interface.

Note
 Both options create the same project structure. Choose based on your workflow preference.

Clone the Accelerator Directly (Recommended)

Use the following one-liner commands to clone the appropriate accelerator for your project type.

For DMN projects, use the following command:

git clone git@github.com:IBM/bamoe-canvas-quarkus-accelerator.git -b 9.3.1-ibm-0006-quarkus-dmn YOUR-PROJECT-NAME
cd YOUR-PROJECT-NAME

For DRL (Rules) projects, use the following command:

git clone git@github.com:IBM/bamoe-canvas-quarkus-accelerator.git -b 9.3.1-ibm-0006-quarkus-drl YOUR-PROJECT-NAME
cd YOUR-PROJECT-NAME

Command details:

Repository git@github.com:IBM/bamoe-canvas-quarkus-accelerator.git

Public IBM accelerator repository.

Branch/Tag: -b 9.3.1-ibm-0006-quarkus-dmn (or -drl)

Specifies the accelerator version for BAMOE 9.3.1.

Project Directory: YOUR-PROJECT-NAME

Your project directory name.

Use the accelerator version that corresponds to your target BAMOE release.

For BAMOE 9.3.1

Use 9.3.1-ibm-0006-quarkus-dmn or 9.3.1-ibm-0006-quarkus-drl.

For other versions

Check available tags, by using git ls-remote --tags git@github.com:IBM/bamoe-canvas-quarkus-accelerator.git command.

Use BAMOE Canvas Web Interface

Using BAMOE Canvas Web Interface provides a visual, web‑based workflow that requires no Git commands, offers immediate previews of your DMN/BPMN models, and makes sharing and collaboration easy.

To create your project using the BAMOE Canvas web interface, do the following steps:

  1. Open BAMOE Canvas in your browser.

  2. Create or open your DMN/BPMN files in BAMOE Canvas.

  3. Apply the accelerator:

    1. Click on the Accelerators menu

    2. Select the accelerator from the list.

    3. Configure project settings.

  4. Download the generated project as a ZIP file

  5. Extract and build:

    unzip your-project.zip
cd your-project