This section describes the steps you will need to take to upgrade Business Services projets developed with BAMOE versions 9.2.0. See the following docs if you are upgrading from a version prior to this:

This guide will walk you through upgrading your:

  • BAMOE development environment with BAMOE Maven repository, BAMOE Canvas, and BAMOE Developer Tools for VS Code

  • Business Service(s) project(s)

  • BAMOE production environment with BAMOE Management Console and upgraded versions of your Business Services

Step 1: Download product archives

Start by downloading the product archives from either IBM Fix Central which requires an active support subscription to IBM BAMOE, IBM Passport Advantage, or via the IBM Business Automation Manager Open Editions Developer Program. For more information see BAMOE 9.2 Download Document.

Step 2: Upgrade your BAMOE development environment

When you upgrade your BAMOE development environment, you must upgrade BAMOE Maven repository, BAMOE Canvas, and BAMOE Developer Tools for VS Code.

Upgrade BAMOE Maven repository

It is recommended using the blue-green deployment strategy for Maven artifacts to be available for both your current version and BAMOE version 9.2.1.

If you are using the BAMOE Maven repository .zip instead of BAMOE Maven repository container images, simply extract the contents of BAMOE Maven repository .zip version 9.2.1 to your local Maven repository.

In case you have installed BAMOE Maven repository in a Maven Repository Manager such as Artifactory or Nexus, follow the steps in Installing → BAMOE Maven repository to install the new BAMOE Maven repository version 9.2.1.

Upgrade BAMOE Canvas

The 9.2.1 version of BAMOE Canvas is a drop in replacement for the 9.2.0 version (see Installing → BAMOE Canvas). The projects you saved to your browser before the upgrade can simply be opened after installing the new version.

If you prefer to install a parallel version using blue-green deployment strategies you can import projects into the newly installed version (see Importing existing projects) as long as the DNS domains between installations are different. If the DNS domains between installations are the same, your imported projects automatically show up in the new installation when you open it in your browser.

Note

If you have customized your previous BAMOE Canvas installation, remember to apply the same Environment Variables to the new installation. The same applies for customized container images for BAMOE Canvas Dev Deployments.

Upgrade BAMOE Developer Tools for VS Code

BAMOE Developer Tools for VS Code versions are managed by the Extension update mechanism in VS Code. You can set automatic update or manage it manually when notified. Because of version differences in the models supported by the BPMN, DMN, and Test Scenario editors it is recommended to choose when you upgrade to avoid issues when running models in services that have not been upgraded when the tools are upgraded.

See BAMOE Developer Tools for VS Code.

Step 3: Upgrade your Business Service(s) project(s)

Business Service(s) project(s) can be upgraded by changing its Maven dependencies and configuration files.

The following tools are required to upgrade your Business Service projects to BAMOE version 9.2.1:

Once your BAMOE development environment is upgraded, it is straightforward to upgrade your Business Service(s) project(s) on BAMOE 9.2.0 to BAMOE version 9.2.1.

The project structure is not changed, updates only need to be made to the dependencies versions, some dependency names, and files.

  1. Upgrade the Quarkus version in the project POM file to the currently supported version 3.20:

  1. Upgrade the BAMOE BOM in the project POM file to 9.2.1-ibm-0005:

    <dependency>
  <groupId>com.ibm.bamoe</groupId>
  <artifactId>bamoe-bom</artifactId>
  <version>9.2.1-ibm-0005</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

  1. If you’re upgrading a Business Service project containing stateful Workflows, upgrade the Quarkus Dev UI to its new artifactId.

    <dependency>
-  <groupId>org.jbpm</groupId>
-  <artifactId>jbpm-quarkus-devui</artifactId>
+  <groupId>com.ibm.bamoe</groupId>
+  <artifactId>bamoe-quarkus-devui</artifactId>
</dependency>

  1. If you are using the BAMOE Management Console and running your Business Services with the quarkus-oidc-proxy extension you will need to upgrade the extension from version 0.1.2 or 0.1.3 to version 0.2.2 in your POM file. This is because of the Quarkus version upgrade from 3.15 to 3.20 (see Securing Business Service API endpoints)

    <dependency>
  <groupId>io.quarkiverse.oidc-proxy</groupId>
  <artifactId>quarkus-oidc-proxy</artifactId>
-  <version>0.1.2</version>
-  <version>0.1.3</version>
+  <version>0.2.2</version>
</dependency>

  1. Update the application.properties file.

    BAMOE version 9.2.1 does not fully support the Quarkus Dev Services and hence it is required to disable this feature by adding the following line to the src/main/resources/application.properties file:

     + quarkus.devservices.enabled=false

    If your Business Service project uses io.quarkus:quarkus-oidc, you may also need to add the following line:

     + quarkus.smallrye-openapi.auto-add-bad-request-response=false

    This fixes a known limitation with auto-generated OpenAPI specifications while using the io.quarkus:quarkus-oidc extension.

  1. If your Busines Service project was using org.jbpm:jbpm-quarkus-devui and you upgraded it to com.ibm.bamoe:bamoe-quarkus-devui, you also need to update its configuration:

     - jbpm.devui.users.<username>.groups=<comma separated list of groups>
 + bamoe.devui.users.<username>.groups=<comma separated list of groups>
Note

Refer to Quarkus 3.20 LTS migration guide for any other change related to Quarkus.

Step 4: Verify the upgrade of your Business Service(s) project(s)

  1. To verify that your upgrade is successful, build the project one more time using Maven’s standard command or any other customized build command you might have in your project.

    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 Business Service project on BAMOE version 9.2.1.

Step 5: Upgrade your BAMOE production environment

After upgrading your Business Services source code (Step 3), you need to upgrade BAMOE Management Console and your stateful Workflows database before deploying a new version of the upgraded Business Services.

It is recommended that you use the blue-green deployment strategy for upgrading BAMOE Management Console so that you still have a reliable way of managing live Business Services that might not have been upgraded to BAMOE version 9.2.1 yet. Once all your Business Services are running BAMOE version 9.2.1, you can safely remove your previous BAMOE Management Console installation.

If you are getting started with stateful Workflows, follow Installing → BAMOE Management Console for information on installing BAMOE Management Console for the first time in your production environment.

Once you have a new installation for BAMOE Management Console version 9.2.1, you can follow the standard guidance on how to deploy a new version of your Business Services (see Building Business Services executables and Deploying Business Services).

Upgrading your stateful Workflow database(s)

You can upgrade your database(s) used by Business Services that run stateful workflows in BAMOE from version 9.2.0 to 9.2.1. Perform the upgrade using the database migration scripts included in the bamoe-9.2.1-db-utils.zip archive.

The archive provides scripts named from—​9.2.0—​to—​9.2.1.sql for each subsystem in a Business Service that uses the Compact Architecture. These subsystems are Data-Index, Data-Audit, Jobs Service, User Tasks, and Runtime Persistence.

Before you begin, make sure you upgrade your Business Services and your database(s) together. Business Services running BAMOE 9.2.0 will not work with a database that you have already migrated to BAMOE 9.2.1.

To upgrade safely:

  • Back up your PostgreSQL or Microsoft SQL Server database

  • Test the migration in a staging environment

  • Apply the scripts sequentially for each subsystem

  • Schedule downtime for production

  • Verify that all services function correctly after the upgrade

Avoid using KIE Flyway for automatic database schema migration in production environments. Instead, apply the scripts manually to maintain control and reduce the risk of issues.

For more information, see Creating your database schema for stateful Workflows based on BAMOE Installation DDL scripts and Overview of stateful Workflows with Compact Architecture.