Updating Bonita Runtime with Bonita Update Tool

Guide on how to update Bonita Runtime main version (single or multiple nodes) using Bonita Update Tool.

Updating means moving from one Bonita version to a newer one, to benefit from:

new features (in Main versions)
technology updates (in Main versions)
bug fixes (in Maintenance versions)

Overview

This page explains how to update Bonita Runtime starting from version 7.10.0 till the latest available Bonita Runtime version. Short procedure : Service stopped, update the data, install a new environment, test non-updated elements behavior and compatibility with new bonita version. Detailed version : Updating Bonita bundle: step-by-step procedure.

There is only one version of Bonita Update Tool: Bonita Update Tool 3.x.

Pre-requisite

The Update Tool requires a Java 11 JRE

How works Bonita Update Tool

Bonita Update Tool contains a set of scripts that execute changes on the data for making it compatible with a newer main version of Bonita Runtime. The tool is provided as a zip archive that contains an executable script to determine your current version and to request the targeted main Bonita version for the update.

The update process is step-based, with each Bonita main version being equal to a step.
The script manages the sequence of steps from your current version to the targeted main version and supports MySQL, Postgres, Oracle, and Microsoft SQL Server. There is no update for H2 database.

Can Bonita Update Tool be used to upgrade/downgrade between community and subscription?

The answer is “NO”. The Bonita Update Tool does not help you upgrade/downgrade between the community/subscription versions, so you cannot change edition at the same time as updating.

Bonita Runtime version to target

Always update to the latest main release by using the Bonita Update Tool. Maintenance releases often contain bug fixes made shortly after the release of subsequent main releases.

For example: Bonita 7.13.2 contains fixes for certain bugs that were found earlier in the 7.13.x versions (like 7.13.0 and 7.13.1). To get all of those fixes, update to the 7.13.2 maintenance version instead of 7.13.1.

Download

Download the target Bonita version bundle and the adequate update tool for your Edition from the Bonitasoft web site for Bonita Community edition or from the Customer Service Center for Bonita Subscription editions. You will also have to download a Tomcat server that matches the target Bonita Runtime version.

Licenses

If you are running a Bonita Subscription edition, you need a valid license for your Bonita target version. If you are updating to a new maintenance version within the same main version, your license remains valid after the update.

Things to know before launching the update

Special attention required on:

Custom reports : Up to Bonita 2021.1 (Bonita Runtime 7.12) they may continue working, depending on the custom code you added. Starting with Bonita 2021.2 (Bonita Runtime 7.13), custom reports will not be supported in Bonita Runtime anymore. They have been replaced with a standalone Enterprise only - Reporting Application.
Dynamic Permissions : Starting from Bonita 2022.1, Dynamic Permissions are available only in Subscription edition. This means that for Community edition, the configuration files/folders remain available but the functionality will not work, without additional custom code or upgrade to Subscription edition.
Several bugs affect legacy Bonita versions by preventing a smooth Bonita Runtime update with BPM services paused when:
- The source version is older than Bonita 7.8.0, and the target version is between Bonita 7.8.0 and Bonita 7.11.5
- The source version is older than Bonita 7.10.5 and the target version is older than Bonita 2021.1
Deployed process definitions: The processes will continue to run using the definition created in the previous Bonita version.
If you have added custom indexes to certain tables in the Engine database, you must remove them before updating to a later version. If you do not remove these indexes, the update process will not complete.
Process definition sources (.bos files) require a manual update. Update these by importing them into the new version of Bonita Studio.

Before launching the update script, there are manual activities to be done:

Go through the release notes of all the versions till the one targeted for the update, for changes/deprecations/removals and see if they impact your existing developments.

For example: when updating from 7.10.y to 7.11.0, you will need to read all the release notes in between those versions.

Go through the Special cases and Troubleshooting paragraphs below.
Secure the update by doing backups. Better safe than sorry.
Check that the database version is up-to-date and supported by the new Bonita version.
Runtime tomcat server custom configuration: You will need to re-apply your customizations after the update process finishes.
Runtime setup folder custom configuration is kept in the database: Custom configurations made and pushed from the setup folder in the previous version are kept in the database. However, to benefit from the changes and improvements made in the product, you may want to compare the files you pull from your database and the target version files available in the setup/platform_conf/initial folder.
Custom connectors, actor filers, data types, custom pages, RestAPI extensions: will for sure continue to work in the new version if no custom code has been added, default Bonita code. If you did add custom code, before starting the update, check in the release notes for any breaking changes and test them thoroughly after the update.

Following elements will be updated automatically when launching the update script:

Engine server
Engine database (including all data on active and archived process instances)
Organization definition
Log files from the previous versions will not be touched. A new dedicated folder for the target version will be created to store the log files.
Runtime data

When the script has finished executing, you will have to complete the update procedure by unzipping and configuring new bundle’s version.

Go through the paragraph Updating Bonita bundle: step-by-step procedure for step-by-step instructions.

BACKUPS

Database files

From database point of view, as any operation on a productive system, an update is not a zero-risk operation. Therefore, it is necessary to backup your database before launching the updating procedure.

Configuration files

As mentioned above, Runtime setup folder custom configuration made and pushed from the setup folder in the previous version will not be reseted to the default version in the database.

However, having a backup of your configuration files before launching the updating procedure is HIGHLY recommended, in case you need to merge custom properties and configurations to the target Bonita Runtime. Use the platform setup tool to pull the configuration from the database and save a backup of your setup folder after the pull:

There is below a Linux example:

cd setup
./setup.sh pull

Look&Feel

Starting with Bonita 2021.2 (Bonita Runtime 7.13), Bonita Applications replaced Bonita Portal. If you need to use some of the Portal Look&Feel assets in the themes of your applications, make sure you create backups of those files before launching the updating procedure.

JRE requirements

Based on your target Bonita version, check whether JRE update is required in your environment before launching the update process:

JRE version

Bonita version

JRE version 11

If targeting an update to Bonita 2021.2 (7.13) or later

JRE version 17

A JRE 17 is not required to run the update tool. But you will need one to run Bonita 2024.1 (10.0) or later

For more info, see Support Guide and Supported Environment Matrix for Server.

Database

Generally, the update script supports MySQL, PostgreSQL, Oracle, and Microsoft SQL Server.

Prior to running the Update tool, please:

Check the detailed database requirements to see if updating your database version is required or not.

If an update is required, make sure to apply all the RDBMS customizations required by Bonita when setting up the new database version.

If custom indexes have been added to certain tables in the engine database, they should be removed them before launching the update procedure. If not removed, the update procedure will not be completed.

There is no update for H2 database.

Drivers

Make sure you double-check that you use the official driver version that matches your database version. Having the correct database driver is mandatory for a smooth update.

If you are using an Oracle database, please follow the instructions for Oracle driver download.

Particularly, if you use Oracle 12.2.0.x.y and are updating to Bonita 7.9.n or 7.10.n, then remove the existing ojdbc8-19.3.0.0.jar file, and add the specific JDBC driver to bonita-update/lib. If you use Oracle or Microsoft SQL Server, add the JDBC driver for your database to bonita-update/lib. This is the same driver as you have installed in your web server lib directory. The driver for Oracle 19.3.0.0 is already embedded in bonita-update/lib. If the target version of the update is Bonita 7.9 or greater, you must upgrade to Oracle 12c (12.2.x.y).

Estimated required time

Bonita Runtime must be shut down during update activities. The time required depends on several factors like your database volume, the gap between the source and the target version and your system configuration, hence it is difficult for Bonita to be precise about the required amount of time. However, the following example can be used as a guide:

From Bonita 7.13.3 to Bonita 7.14.0

Criteria

Data

Database entries

archive processes: 7,086,642
processes: 147,903
archive flownodes: 11,532,868
flownodes: 147,903
documents: 323,387
connectors: 13,005
tasks: 5,330,129
cases: 2,460,816
data instances: 142,186

Source version

7.13.3

Target version

7.14.0

Time required

< than 1 second

From Bonita 7.10.0 to Bonita 7.14.0

Criteria

Data

Database entries

archive processes: 5024
processes: 2021
archive flownodes: 86518
flownodes: 2021
documents: 7045
connectors: 1001
data instances: 2021

Source version

7.10.0

Target version

7.14.0

Time required

~ 18 seconds (without profiles associated to profile entries)
~ 4 minutes (with 10000 profiles but 1000 linked to ~6 profile entries ⇒ ~1000 applications generated)

Updating Bonita bundle: step-by-step procedure

This section explains how to update a platform that uses one of the Bonita bundles.

First, download the target version bundle and Bonita Update Tool for your edition:

from the Bonitasoft site for Bonita Community edition
from the Customer Service Center for Bonita Subscription Pack editions

Database

The steps are as follow:

Check that your current RDBMS version is compliant with the versions supported by the targeted version of Bonita (see RDBMS requirements)
Unzip the Bonita Update Tool zip file into a dedicated directory that can be called bonita-update.
Configure the database properties needed by the update script, by editing the bonita-update/Config.properties file with the following information:

Property

Description

Example

db.vendor

Database vendor

postgres

db.driverClass

The driver used to access the database

org.postgresql.Driver

db.url

The url of the Bonita Engine database

jdbc:postgresql://localhost:5432/bonita-update

db.user

The username used to authenticate to the database

bonita

db.password

The password used to authenticate to the database

bpm

If you are using MySQL, add ?allowMultiQueries=true to the URL. For example, db.url=jdbc:mysql://localhost:3306/bonita-update?allowMultiQueries=true.

Stop Bonita

IMPORTANT: Do not pause the BPM services (or activate the maintenance mode) before you stop the application server, unless your Bonita source version is higher than 2021.1, otherwise it will cause problems.

Stop the application server.
IMPORTANT: Back up your runtime nodes and databases.

Run Bonita Update Tool

Go to the directory containing Bonita Update Tool/Bonita Migration Tool.
Run the appropriate update script:

Version

Edition

Script

Bonita Update Tool 3.x

Community edition

bonita-update-tool (Linux)
bonita-update-tool.bat (Windows)

Bonita Update Tool 3.x

Subscription edition

bonita-update-tool-sp (Linux)
bonita-update-tool-sp.bat (Windows)

A script called check-update-dryrun is available. It can be used as a pre-update check as it does all the verification without actually updating the elements. This is equivalent to running the update script with a --verify option.

Update tool’s execution

The script behind the Update tool detects the current version of Bonita and displays a list of the versions available for update. Once you specify the version you are targeting, the updating procedure starts.

All along script’s execution you will be informed of the advancement level with user messages, that you will be asked to confirm for proceeding to the next step. The messages contain important information and we strongly advice you to keep a foreground execution. In case you prefer a background execution without user messages, set to “true” ` (-Dauto.accept=true)` system property.

At the end of the update script execution, the new Runtime version, the database update and the time taken for migrating all the elements will be mentioned in a dedicated user message.

After the update tool is completed

Reminder The old Tomcat server cannot be used. You will have to install one that matches the target Bonita Runtime version along with the Bonita binaries.

Setup the target Bonita bundle

Unzip the target bundle version into a directory. In the steps below, this directory will be called bonita-target-version.

Configure the bundle to use the updated database. Do not recreate the database and use the setup tool of the bonita-target-version. Edit the bonita-target-version/setup/database.properties file to point to the updated database.
Download the configuration from database to the local disk using the setup tool of the bonita-target-version.

There is below a Linux example:
```
cd setup
./setup.sh pull
```
After the setup pull, you can change your configuration into the bonita-target-version/setup/platform_conf/current folder.

Please refer to the guide on updating the configuration file using the platform setup tool
When done, push the updated configuration into the database:
```
./setup.sh push
```

Specific configuration

If you have done specific configuration and customization actions in your server source version, re-do it by configuring the application server in folder bonita-target-version/server.

Manual operations

Perform a diff between the source version and the target version of tenants/[TENANT_ID]/tenant_portal/dynamic-permissions-checks.properties and put the additional lines into the file tenants/[TENANT_ID]/tenant_portal/dynamic-permissions-checks-custom.properties

Licenses

Put a new license in the database: see Runtime configuration for further details.

Example for Linux cd setup vi database.properties ./setup.sh pull ls -l ./platform_conf/licenses/

If there is no valid license in the /platform_conf/licenses/, these 2 pages will help you request and install a new one:

Setup tool Then, install the new license.

Code exemple cp BonitaSubscription-7.n-Jerome-myHosname-20171023-20180122.lic ./platform_conf/licenses/ ./setup.sh push

Start the new Bonita Runtime

Start the application server and clear your browser cache before you start Bonita Applications or you might see old, cached versions of Portal or Applications pages instead of the new versions.
Log in to Bonita UIs and verify that the updating procedure has completed.

The Bonita update is now complete.

Special cases

Updating to Bonita 2024.3 (10.2) or a greater version in Community edition

Only PostgreSQL is supported for Bonita 2024.3 (10.2) and greater versions for Community edition.

If you are runing Bonita with Docker Compose

When using the Docker Compose installation, you can use scaling to stop and start your Bonita application in the bonita node(s). Stop your bonita node(s) or your custom application node(s) by scaling down to 0.

docker-compose up --scale bonita=0 --no-recreate -d

After updating the docker-compose.yml file to the image built with the new Bonita version, scale up the service when you want to restart Bonita.

Updating to Java 17 in Bonita 2024.1 (10.0) or a greater version

Bonita 2024.1 (10.0) and greater require Java 17.

The Java 11 to 17 update implies some API removals. Make sure that all your custom code and dependencies are compliant with those changes.

Another pitfall of Java 17 migration is the reflection access restriction on declared java modules. By default, Bonita opens the following modules:

Required by Tomcat:
- java.base/java.lang=ALL-UNNAMED
- java.base/java.io=ALL-UNNAMED
- java.base/java.util=ALL-UNNAMED
- java.base/java.util.concurrent=ALL-UNNAMED
- java.rmi/sun.rmi.transport=ALL-UNNAMED
- java.base/java.nio=ALL-UNNAMED
- java.base/sun.nio.ch=ALL-UNNAMED
- java.management/sun.management=ALL-UNNAMED
- jdk.management/com.sun.management.internal=ALL-UNNAMED
Required for Xstream serialization:
- java.base/java.time=ALL-UNNAMED
- java.base/java.time.chrono=ALL-UNNAMED
- java.base/java.text=ALL-UNNAMED
Required by Webservice connector for Xstream serialization:
- java.xml/com.sun.org.apache.xerces.internal.dom=ALL-UNNAMED
- java.xml/com.sun.org.apache.xerces.internal.xni=ALL-UNNAMED
Required by Salesforce connector for Xstream serialization:
- java.xml/javax.xml.namespace=ALL-UNNAMED

The Bonita Runtime still uses Xstream under the hood for process variable serialization and client/server API serialization. As this library rely on Java reflection, you might be impacted by this new restriction when using custom classes in your process variables and/or connectors output.

Updating to Java 11 in Bonita 7.9 to Bonita 2023.2 (9.0)

Bonita 7.9 to Bonita 2023.2 (9.0) support Java 11.

Updating an existing platform to Java 11 is neither easy nor a painless endeavour. It’s just has to be done.

Here are the steps to follow:

Update Bonita Runtime to Bonita 7.9.0 as usual, and keep running it in Java 8
Verify that everything works as expected
Test the target Runtime in Java 11, on a test environment
Update what is required on the production server
Switch it to Java 11

The main parts that require attention and testing are connectors and custom code.

Also, custom connectors, groovy scripts, REST API extensions etc. are not migrated and might not work as expected in Java 11.

Special attention has to be given to custom code dependencies, as they might:

either not work in Java 11,
work fine but be in conflict with Bonita dependencies
the script might use dependencies previously included in Bonita, but accessible in a different version.

Thorough testing has to be carried out to ensure there is no regression when migrating Bonita to version 7.9 and greater.

Updating to Bonita 7.11 or a greater version using Oracle

Bonita 7.11 and greater versions support Oracle 19c version.

To update to Bonita 7.11 or a greater version when using Oracle, follow this procedure:

Shut down Bonita Runtime
Run the migration tool to update to Bonita 7.10.5, following the procedure above
Update your Oracle database server to version 19c (version 7.10.x is compatible with 12c and 19c.)
Run the migration tool again to update to Bonita 7.11.0 or greater version
Restart the new Bonita Runtime

When updating the Oracle database make sure that the initialization parameter Compatible is not set to a previous version. You can check this with the query: SQL> SELECT name, value FROM v$parameter WHERE name = 'compatible';

Updating to Bonita 7.11 or a greater version using SQL Server

Bonita 7.11+ supports SQL Server 2017 version.

To update to Bonita 7.11+ when using SQL Server, please follow this procedure:

ensure your Bonita platform is shut down
run Bonita Update tool to update Bonita platform to version 7.11.0 or newer, following the above procedure
then upgrade your SQL Server database server to version 2017
restart your updated Bonita platform

Updating maintenance versions starting with Bonita 7.11

Starting with Bonita 7.11, updating between maintenance versions of the same main version does not require the Bonita Update Tool, just follow below steps:

Download the new bundle version from Bonitasoft site for Bonita Community edition or from the Customer Service Center for Bonita Subscription editions
Shut down your old Bonita Runtime
Unzip and configure the new bundle This means copying the configuration files of the old Bonita Runtime, mainly database.properties, server.xml, internal.properties if changes have been made.
Start the new bundle
Delete the old bundle files

Updating a Bonita Runtime cluster

A Bonita Runtime cluster must have the same binary version of Bonita and database version on all nodes. To update a Bonita Runtime cluster, download the right Bonita dedicated tool:

From Bonita version

Till Bonita version

Tool version

6.x.y

7.0.0

Bonita Migration Tool 1.X A dedicated tool is available for Performance cluster, default Performance migration tool does not support cluster update.

7.0.0

7.13.y

Bonita Migration Tool 2.X Cluster update included.

7.10.y

latest main version

Bonita Update Tool 3.X Cluster update included.

In a cluster environment, you need to STOP ALL your nodes and update them before starting them with the new maintenance version. On one node, follow the procedure above to update Bonita Runtime. When the update is complete on one node, follow steps 12 and 16 on all the other nodes. The update of the cluster is then complete, and the cluster can be restarted.

Migrate your client applications

If you have applications that have Bonita as client, you will have to change your client code or library. For backward compatibility checks, refer to the release notes.

In addition, if your application connects to Bonita Engine using the HTTP access mode, see the bonita-client library documentation page.

Troubleshooting

Translation are missing in Application Directory and Admin Case list

Symptom: Starting from Bonita 2021.2, when creating an application using pages available in resources list of previous Bonita versions, translations may be missing in Bonita Application Directory. Cause: The translations are in localization.json and not in the exported pages. Solution: If an app has been created using a page exported from the resources list in a certain version, you will need to either reexport the pages from the new version or update your app by adding the localization.json of the new version. This way the right translations will be available.

Timers are stuck after updating to Bonita 7.10.0 or greater versions

Symptom: When updating to Bonita 7.10.0 or a greater version, the timers on processes do not work anymore. Cause: A bug in the pause/resume mechanism of tenant services, fixed in Bonita 7.12.1. This issue happens because the BPM services were paused before the update was performed. Solution: If the BPM services were paused before the update or had to be paused for whatever reason, then to resolve this, you need to execute the following database requests after the update completes, and before you restart your Bonita Runtime:

DELETE FROM QRTZ_PAUSED_TRIGGER_GRPS;

UPDATE QRTZ_TRIGGERS SET TRIGGER_STATE = 'WAITING' WHERE TRIGGER_STATE = 'PAUSED';

After this operation, the table QRTZ_PAUSED_TRIGGER_GRPS should be empty, and all the triggers in the QRTZ_TRIGGERS table should be in state waiting, and not paused.

Some foreign keys are duplicated

This issue is fixed in Bonita 7.11.6, without any action required from the platform administrator.

Symptom: After updating to a Bonita version comprised between 7.11.0 and 7.11.5, after re-installing/updating the BDM, some foreign key constraints are effectively duplicated: there are foreign keys that refer to the same columns and tables, but with a different name. Cause: A bug was introduced in Bonita 7.11.0 by upgrading an external library, Hibernate, from version 4 to 5. This new version introduces a known bug.

Solution: Doing nothing is an option, as there are no changes in Bonita’s behaviour. Still, if you wish to clean your BDM database, follow the procedure below:

Stop your bonita server
Open the database in an edition tool or execute in command line the relevant commands.

Select all the foreign keys on a table of your BDM objects:

MySQL

SELECT TABLE_NAME,COLUMN_NAME,CONSTRAINT_NAME, REFERENCED_TABLE_NAME,REFERENCED_COLUMN_NAME FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE WHERE REFERENCED_TABLE_SCHEMA = '<your_business_data_db_name>' AND REFERENCED_TABLE_NAME = '<your_table_name>';

MS SQL Server

select name [foreign key constraint name], OBJECT_NAME(parent_object_id) [created table], OBJECT_NAME(referenced_object_id) [referenced table] from sys.foreign_keys where parent_object_id = OBJECT_ID('<your_table_name>') OR referenced_object_id = OBJECT_ID('<your_table_name>')

PostgreSQL

SELECT conname, pg_catalog.pg_get_constraintdef(r.oid, true) as condef FROM pg_catalog.pg_constraint r WHERE r.conrelid = '<your_table_name>'::regclass AND r.contype = 'f' ORDER BY 1

These requests will give you all the foreign keys on a table. Among these, search for duplicated ones: the duplicated foreign keys should have the following names: FK_<hash> & FK<another_hash>. The two different names should be for keys referencing the same columns on the same table. Delete the one named: FK_<hash>.
Repeat for all the tables of your BDM database.
Start your Bonita Runtime

Guidance is not provided for Oracle, as the situation is impossible. Oracle prevents the creation of 2 identical foreign keys with different names. Instead, the BDM redeployment will fail after migration. Updating to Bonita 7.11.6 or greater versions fixes the issue.