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

Prerequisites

The following tools are required to migrate to BAMOE version 9.1.1:

Procedure

This section describes the process to migrate your projects from version 9.0.x to 9.1.1. Before you start, ensure that you have installed or updated all prerequisite tools.

This migration guide will show two ways of migrating your project. The first, by creating a new project from scratch and moving your existing assets to it. The second, by updating an existing BAMOE version 9.0.x project. You will start by setting 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 the build, reporting and documentation of a project 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.1 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.1 Maven configuration.

Creating a new project from scracth

Now that you have Maven properly configured, you can create a new Maven project to migrate your existing business automation assets to the new BAMOE version 9.1.1. There are several ways to create Maven projects; 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 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 will notice the Maven artifacts being streamed in your console as they are pulled. When the process is complete, you will see 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, 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.1-ibm-0003</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.

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 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 version of the dependency, as that appears from the BOM, so your dependencies will resemble 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) please report it to IBM to be resolved.

See version mapping for BAMOE version 9.1.x.

  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.1 some dependencies had a slight name change, see section, 'Maven libraries mapping guide' in Upgrading and update accordingly.

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

    Depending on the project files you may 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 Excel Files (.xlsx)

    • 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 respective 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. 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.1 project.

Upgrading a BAMOE version 9.0.x project

Upgrading a BAMOE version 9.0.x project to version 9.1.1 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.1 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 1.40.2.Final. Now, both versions are 9.1.1-ibm-0003. 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.1-ibm-0003</kogito.bom.version>
 +++   <version.org.kie.kogito>9.1.1-ibm-0003</version.org.kie.kogito>

  1. Update the dependencies GAV.

    In the BAMOE version 9.1.1 some dependencies had a slight name change, see section, 'Maven libraries mapping guide' in Upgrading 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 is 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.1 does not fully support the Quarkus Dev Services, due to that, it is 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.1 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 and OOPATH syntax. Refer to Drools Rule Language Migration for information on migrating to the latest version of Drools Rule Language (DRL).