This section describes the migration of existing Version 9.0.x applications to Version 9.1.x of IBM Business Automation Manager Open Editions.

Prerequisites

The following tools are required to migrate to BAMOE Version 9.1.x:

Procedure

The project migration from BAMOE Version 9.0.x to BAMOE Version 9.1.x requires a few steps. Before proceeding, ensure that all prerequisite tools are installed or updated, then you need to properly set up Maven.

This migration guide will show two ways of migrating your project. On the first way, you will be creating a new project from scratch and then moving the assets to it. The second way, you will be updating an existing BAMOE Version 9.0.x project. Either way, the first step is to set up the Maven configuration.

Update Maven configuration

Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project’s build, reporting and documentation from a central piece of information. IBM Business Automation Manager Open Editions depends on Maven to build various types of deployable artifacts, such as decision service applications. For a quick start, see the Maven Quick Start Guide.

Since BAMOE Version 9.1.x is based on Quarkus 3, the easiest route is to use the Quarkus Maven Plugin and adjust some of the details in the generated project to align it with BAMOE dependencies and plugins. You can read all about Quarkus and Maven here.

Update Maven settings

On the IBM BAMOE Version 9.0.x the dependencies were hosted on the Maven Central. Now the dependencies are distributed with a container image or a zip file. Refer to BAMOE Version 9.1.x Maven configuration.

Creating a new project from scracth

Now that you have the Maven properly configured, you can move onto the first approach, which is to create a new project from scratch. The first step is to generate a new Maven project so that there is a place to migrate your existing business automation assets to the new BAMOE version 9.1.x. There are several ways to create Maven projects; however, this approach uses a published Maven plugin.

  1. In a terminal window, create a new local folder for the new Maven project, for example, /Users/developer, and navigate to that folder.

  2. Create the project by using Quarkus and the following Maven commands. This creates a Quarkus project called my-sample-decision-service, which is versioned 1.0.0-SNAPSHOT, and includes the extensions resteasy-reactive-jackson, quarkus-smallrye-openapi, quarkus-smallrye-health.

    mvn io.quarkus.platform:quarkus-maven-plugin:3.8.6:create \
    -DprojectGroupId=com.ibm.bamoe.samples \
    -DprojectArtifactId=my-sample-decision-service \
    -DprojectVersion=1.0.0-SNAPSHOT \
    -DplatformGroupId=io.quarkus.platform \
    -DplatformArtifactId=quarkus-bom \
    -Dextensions=resteasy-reactive-jackson,quarkus-smallrye-openapi,quarkus-smallrye-health
    Note

    As you can see from the Maven command, there are a number of possible extensions that can be added to the project for the specific functionality. You can find more information on available extensions at the following locations: Quarkus Extensions, and Kogito Extensions.

    When you create this project, you might get a bunch of Maven artifacts start to stream in your console that are being pulled, and ultimately, you are left with a console message like the following:

    [INFO]
[INFO] ========================================================================================
[INFO] Your new application has been created in /Users/developer/my-sample-decision-service
[INFO] Navigate into this directory and launch your application with mvn quarkus:dev
[INFO] Your application will be accessible on http://localhost:8080
[INFO] ========================================================================================
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.632 s
[INFO] Finished at: 2024-06-11T11:20:51-03:00
[INFO] ------------------------------------------------------------------------

  1. Add the following properties to the pom.xml file by using the row numbers as a guide. This specifies the Maven coordinates for the BAMOE Maven Bill-of-Materials (BOM), which manages all of the associated dependency versions for a specific BAMOE release:

    17   <surefire-plugin.version>3.0.0-M7</surefire-plugin.version>
18   <kogito.bom.group-id>com.ibm.bamoe</kogito.bom.group-id>
19   <kogito.bom.artifact-id>bamoe-bom</kogito.bom.artifact-id>
20   <kogito.bom.version>9.1.0-ibm-0001</kogito.bom.version>
21 </properties>

  1. Replace lines 31-37, which essentially add the bamoe-bom to the list of imported dependencies:

    31  <dependency>
32    <groupId>${kogito.bom.group-id}</groupId>
33    <artifactId>${kogito.bom.artifact-id}</artifactId>
34    <version>${kogito.bom.version}</version>
35    <type>pom</type>
36    <scope>import</scope>
37  </dependency>

    A bill of materials (BOM) is a list of parts or components that are required to build a product. BOMs are ordinary pom.xml files that contain no source code, and their only purpose is to declare their bundled modules.

Important
Always use the Maven Bill-of-Materials (BOM)

It is recommended to use a bill of materials (BOM) to manage project dependencies, as it simplifies dependency management by organizing a group of dependencies under a single version.

It must be noted that the use of a Maven bill-of-materials (BOM) does not add any dependencies to the project. Rather, it functions as a reference for managing the versions of your project’s dependencies (and transient dependencies).

A bill of materials (BOM) can be added to an existing POM file by adding it to the dependencyManagement section as a dependency with a pom type:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.redhat.ba</groupId>
            <artifactId>ba-platform-bom</artifactId>
            <version><!-- See Version Mapping Table --></version>
            <scope>import</scope>
            <type>pom</type>
        </dependency>
    </dependencies>
</dependencyManagement>

When a bill of materials (BOM) is used, it is not necessary to specify the dependency’s version, as that appears from the BOM, so your dependencies end up like the following:

<dependencies>
    <dependency>
        <groupId>org.drools</groupId>
        <artifactId>drools-compiler</artifactId>
    </dependency>
</dependencies>
Note

During the course of your Maven dependency update, if you encounter any dependencies that are not included in the bill of materials (BOM), then use the Maven Library Version noted in the following table:

<dependencies>
    <dependency>
        <groupId>org.drools</groupId>
        <artifactId>drools-compiler</artifactId>
        <version>8.40.0.Final</version>
    </dependency>
</dependencies>

You must also report to IBM that a dependency is missing so that the problem can be resolved in the next release.
Table 1. Version Mapping for IBM BAMOE Version 9.1.x
Product Version BOM Version Maven Library Version

IBM BAMOE 9.1.0

9.1.0-ibm-0001

9.1.0-ibm-0001

  1. Add the IBM ILMT Compliance Library to the pom.xml (this is required to report on subscription entitlement usage within the system):

    40  <dependencies>
41    <dependency>
42      <groupId>com.ibm.bamoe</groupId>
43      <artifactId>bamoe-ilmt-compliance-quarkus-dmoe</artifactId>
44    </dependency>
Note

You might notice that the newly added Maven dependency includes the groupId and artifactId portions of the Maven coordinates but does not specify a version tag. This is due to importing the bamoe-bom into the project, where the various dependency versions are managed.

  1. Add the dependencies.

    For this example, you will be creating a project with only DMN files. So you must add the the Drools Kogito Quarkus dependency. In the BAMOE Version 9.1.x some dependencies had a slight name change, refer to the GAV mapping table and update accordingly.

    45 <dependency>
46   <groupId>org.drools</groupId>
47   <artifactId>drools-quarkus-decisions</artifactId>
48 </dependency>
    Note

    Depending on the project files it will be required to add other dependencies.

  1. Disable Quarkus Dev Services.

    Currently, the Quarkus Dev Services isn’t fully supported, meaning that it should be disabled. To do so, add the following line in the src/main/resources/application.properties file:

    quarkus.devservices.enabled=false

  1. Build the project in the root folder:

    mvn clean package

    You might get Maven streaming text once again, and at the end of it you must have:

    [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  8.023 s
[INFO] Finished at: 2024-06-11T17:09:00-03:00
[INFO] ------------------------------------------------------------------------
    Note

    The choice of extensions determines the imported behavior of the project including adding sample models or testing related code.

  1. Add and update Business Automation assets

    After the project is generated, you must see a project structure in VS Code, similar to the following diagram:

    Example Maven Project in VS Code
    Figure 1. Example Maven Project in VS Code

    As you can see from the figure, a Maven compliant project is generated, including all of the standard folders typically found in a Maven project. The most significant folder is the resources folder, which is where new or migrated business automation asset files must be stored. Examples of supported business automation assets are:

    • Decision Model & Notation (DMN) Models (.dmn)

    • Drools Rule Language (DRL) Files (.drl)

    • Business Process Modeling & Notation (BPMN) Models (.bpmn)

    • Excel Decision Tables (XLS) Files (.xls)

    • Standard Property Files (.properties)

    • Test Scenario Files (.scesim)

      Note

      The proper folder for unit test files is src/test/resources, as this is a testing resource.

      Now, copy all your assets from the BAMOE version 9.0.1 project to the repesctive folders on the new project. As the new project uses Quarkus 3, You must make a few more updates. One of the biggest changes is that Quarkus 3 uses Jarkarta EE 10, meaning that you need to update all javax to jakarta. This is simply achieved by replacing any javax instance over jarkarta, like the following:

       --- import javax.inject.Named;
 +++ import jakarta.inject.Named;
      Note

      Refer Quarkus v3 migration guide for any other change that is related to Quarkus.

  1. Build the project one more time.

    mvn clean package

    You might get Maven streaming text once again, and at the end of it you must have:

    [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  8.023 s
[INFO] Finished at: 2024-06-11T17:09:00-03:00
[INFO] ------------------------------------------------------------------------

    Now you can start using your BAMOE version 9.1.x project.

Upgrading a BAMOE Version 9.0.x project

Upgrading a BAMOE version 9.0.x project to version 9.1.x is straightforward. The project structure hasn’t changed, updates only need to be made to the project versions, some dependency names, and files.

  1. Upgrade the Quarkus version.

    In the BAMOE Version 9.0.x the Quarkus version was 2.16 and for Version 9.1.x it is 3.8.6. To make this upgrade, open the pom.xml file and do the following change:

     ---   <quarkus-plugin.version>2.16.10.Final</quarkus-plugin.version>
 +++   <quarkus-plugin.version>3.8.6</quarkus-plugin.version>
       <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
       <quarkus.platform.group-id>io.quarkus</quarkus.platform.group-id>
 ---   <quarkus.platform.version>2.16.12.Final</quarkus.platform.version>
 +++   <quarkus.platform.version>3.8.6</quarkus.platform.version>

  1. Upgrade the BOM and Kogito versions.

    Previously, the BAMOE Version 9.0.x used the BOM version 9.0.1.Final and Kogito version {KOGITO_VERSION_90x}. Now, both versions are {BOM_VERSION_91x}. Update the following lines in your pom.xml:

           <kogito.bom.artifact-id>bamoe-bom</kogito.bom.artifact-id>
 ---   <kogito.bom.version>9.0.1.Final</kogito.bom.version>
 ---   <version.org.kie.kogito>1.40.2.Final</version.org.kie.kogito>
 +++   <kogito.bom.version>9.1.x-ibm-0001</kogito.bom.version>
 +++   <version.org.kie.kogito>9.1.x-ibm-0001</version.org.kie.kogito>

  1. Update the dependencies GAV.

    In the BAMOE Version 9.1.x some dependencies had a slight name change, refer to the GAV mapping table and update accordingly.

    One of the renamed dependencies is the groupdId=org.kie.kogito and artifactId=kogito-quarkus, which was renamed to groupdId=org.jbpm and jbpm-with-drools-quarkus.

           <dependency>
 ---     <groupId>org.kie.kogito</groupId>
 ---     <artifactId>kogito-quarkus</artifactId>
 +++     <groupId>org.jbpm</groupId>
 +++     <artifactId>jbpm-with-drools-quarkus</artifactId>
       </dependency>

    Bear in mind that it’s required to make changes to any parent pom.xml if applied, but this will not be covered here as it depends on your project setup. This ends the pom.xml changes, next, files that need changes

  1. Update the application.properties file.

    BAMOE Version 9.1.x does not fully support the Quarkus Dev Services, due to that, it’s required to disable this feature and to do that, add the following line to the src/main/resources/application.properties file:

     +++ quarkus.devservices.enabled=false

  1. Migrating the code to Quarkus 3.

    A major Quarkus 3 change, is the usage of Jakarta EE 10, meaning that package imports also need to update from javax to jakarta.

    This is simply achieved by replacing any javax instance over jarkarta, like the following:

     --- import javax.inject.Named;
 +++ import jakarta.inject.Named;
    Note

    Refer Quarkus v3 migration guide for any other change that is related to Quarkus.

  1. Build the project in the root folder:

    mvn clean package

    You might get Maven streaming text once again, and at the end of it you must have:

    [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  8.023 s
[INFO] Finished at: 2024-06-11T17:09:00-03:00
[INFO] ------------------------------------------------------------------------

    Now, you can start using your BAMOE version 9.1.x project.

Compile, Build, Test, Deploy

You can follow the standard guidance on how to maintain your decision service project, including how to build using Maven and how to deploy to your target Kubernetes-based environment. This includes not only creating and publishing the new project to an enterprise GIT repository but also configuring your CI/CD pipeline to pull from GIT and performing a Maven build/test/deploy, etc.

Note

After completing the migration of the project, you might want to consider migrating your technical rules to use new language features, such as rule units or OOPATH syntax. Refer to Drools Rule Language Migration for information on migrating to the latest version of Drools Rule Language (DRL).