Updating Bonita Runtime

This page explains how to update Bonita Runtime (single or multiple nodes) to a newer version of Bonita.

How it works

To update Bonita Runtime you need to use Bonita Migration Tool. There are 2 versions of the migration tool:

  • Version 1.x migrates the elements of Bonita Runtime from version 6.0.2 or later to any version up to 7.0.0

  • Version 2.x migrates the elements of Bonita Runtime from version 7.0.0 or later to any version up to the last one.

For example, if you consider updating from Bonita 6.5.3 to Bonita 7.1.0, you must first update from Bonita 6.5.3 to Bonita 7.0.0 using version 1.x of Bonita Migration Tool, and then update from Bonita 7.0.0 to Bonita 7.1.0 using version 2.x.
You are recommended not to start Bonita 7.0.0 after you update to it, but to proceed immediately with the second phase of the update.

Bonita Migration Tool contains a set of scripts that execute changes on the data to make it compatible with the newer version of Bonita Runtime. This tool is provided as a zip archive and contains an executable script that will determine your current configuration and ask you to which version you want to update.

The update is step-wise, by maintenance version, and the script manages the sequence of steps from your current version to the target version. After each main or maintenance version update, you have the option to pause or continue to the next step.

The migration script migrates the following elements:

  • Engine server

  • Engine database, including all data on active and archived process instances

  • Organization definition

  • Log files from the previous version are not impacted

  • Runtime data (in Bonita Home before Bonita 7.3, in the database after)

  • Configuration files (in Bonita Home before Bonita 7.3, in the database after), replaced with the default configuration files of the new version

The following are not migrated automatically:

  • Runtime custom configuration (in Bonita Home before Bonita 7.3, in the database after). Reapply your customizations manually after the migration script has finished. If the target version of the update is Bonita 7.3 or greater, you can use the setup tool).

  • Deployed process definitions: The processes will continue to run using the definition created in the previous version of Bonita.

  • Process definition sources (.bos files): Migrate these by importing them into the new version of Bonita Studio.

  • Business Data Model, and the business database: if the updating path includes version 7.0.0,7.2.0 or 7.2.4, the Business Data Model must be redeployed after the update. To do so:

    1. Before the update, log into the Super Administrator application

    2. Pause the BPM Services

    3. Redeploy the BDM once the update is done. Otherwise, no action is required.

  • Custom connectors, actor filers, data types: These might continue to work in the new version, but should be tested, depending on your custom code.

  • Custom pages: These might continue to work in the new version, but should be tested depending on your custom code.

  • REST API Extensions: These might continue to work in the new version, but should be tested depending on your custom code.

  • Custom reports up to Bonita 2021.1: These might continue to work in the new version, but should be tested depending on your custom code.

Starting with Bonita 2021.2, custom reports will not be supported in Bonita anymore. They will be replaced by another functionality in further versions of Bonita.

When the script has finished, you need to complete the updating procedure by unzipping and configuring a bundle for the new version.
See Updating Bonita bundle: step-by-step procedure for step-by-step instructions.

Things to know before launching the updating procedure

Version to target

You should always update to the latest version of a main release, even if not the latest Bonita version.
Indeed, such maintenance versions might contain bug fixes made after the release of subsequent main releases.
For example, Bonita 6.5.4 contains fixes to certain bugs that were found in early Bonita 7.x.y versions, up to Bonita 7.1.0.
When you are ready to update from Bonita 6.5.4 to a Bonita 7.x.y version, make sure you update to at least Bonita 7.1.1 to be sure that these fixes are present in your new version after the update.

Update + Upgrade?

Bonita Migration Tool modifies files on your runtime, so you cannot change edition at the same time as updating.

Licenses

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

Backups

The updating operations reset the Bonita configuration files to their default versions, for new settings to be applied (from the $BONITA_HOME folder before Bonita 7.3.0 or inside the database for Bonita 7.3.0 and greater versions).
Therefore, you must backup your configuration files before launching the updating procedure.
You will need to merge custom properties and configurations to the target Bonita Runtime.

Furthermore, from the database point of view, as any operations on a production system, an update is not a zero-risk operation.
Therefore, it is also strongly recommended to backup your database before launching the updating procedure.

JRE requirements

  • Bonita 7.0 only supports JRE version 7. If updating to Bonita 7.0 to 7.4.x, please update your JRE to version 7.

  • Bonita 7.5 only supports JRE version 8. If updating to Bonita 7.5 to Bonita 2021.1-0811, please update your JRE to version 8.

  • Bonita 2021.2 only supports JRE version 11. If updating to Bonita 2021.2 or greater, please update your JRE to version 11.

Database

  • The migration script supports MySQL, PostgreSQL, Oracle, and Microsoft SQL Server. There is no migration for h2 database.

  • The target Bonita version may not support the version of the database used with your source Bonita version. You may then need to update the version of your database prior to running the migration tool. To make sure:

  • If you have added custom indexes to certain tables in the engine database, you must remove them before lauching the update procedure. If you do not remove these indexes, the update procedure will not be completed.

Starting with Bonita 2021.2, there is no more Bonita Portal. Bonita is all applications. 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.

Custom configuration

To update Bonita to a target version Bonita 7.3 or greater: Starting with Bonita 7.3, there is no more bonita home folder.
What this means:

  • If you have customized your configuration, you will have to use the setup tool to send your customized configuration files to the database where the configuration is stored

  • If your current installation does not have any custom configuration, then you do not need to configure the bundle any further

Estimated time required

Bonita Runtime must be shut down during the update.
The time required depends on several factors including the database volume, the number of versions between the source version and the target version, and the system configuration, so it is not possible to be precise about required time.
However, the following example can be used as a guide:

Database entries:

data: 22541
flownode: 22482
process: 7493
connector: 7486
document: 7476

Source version:

6.0.2

Target version:

6.3.0

Time required:

2.5 minutes

Updating Bonita bundle: step-by-step procedure

Update steps

Download

Download the target version bundle and the migration tool for your Edition from the Bonitasoft web site for Bonita Community edition or from the Customer Service Center for Bonita Subscription editions.

Database

  1. Check that your current RDBMS version is compliant with the versions supported by the targeted version of Bonita (see above)

  2. Unzip the migration tool zip file into a directory. In the steps below, this directory is called bonita-update

  3. 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 in 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).
    Make sure you double-check that you use the official driver version that matches your database version.
    The correct driver is mandatory for a smooth update: 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.

  4. Configure the database properties needed by the migration script, by editing bonita-update/Config.properties.
    Specify the following information:

    Property Description Example

    bonita.home

    The location of the existing bonita_home. Required only until Bonita 7.3

    /opt/BPMN/bonita (Linux) or C:\\BPMN\\bonita (Windows)

    db.vendor

    The database vendor

    postgres

    db.driverClass

    The driver used to access the database

    org.postgresql.Driver

    db.url

    The location 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.

Look & Feel

Exporting the Look & Feel is not needed, as Bonita Portal has been replaced by Bonita applications. However, the backup of your Look & Feel files may be helpful to create the applications themes.

Stop Bonita

  1. Pause the BPM Services Generally speaking, pausing (or not) the BPM services before the update should not impact the updating procedure. There are however a few special cases:

    • If the source version is older than Bonita 7.3.0 and if you are using a BDM, your BDM will have to be redeployed after the update is done (see above). In this case, it is recommended that you stop your BPM services before updating, so as to be able to redeploy your BDM immediately after the update (and not having to deal with eventual errors in automated processes as you restart your platform after the update procedure is over).

    • Several bugs affect legacy versions of Bonita that prevent a smooth update of a Bonita Runtime with BPM services paused in special cases:

      • The source version is older than Bonita 7.8.0, and the target version is comprised 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

    • Therefore, while it is recommended to always update to the latest version of Bonita, if your target version is not 2021.1 or greater, it is necessary to update with BPM services running.

  2. Stop the application server.

  3. IMPORTANT:Back up your runtime nodes and databases

Run Bonita Migration Tool

  1. Go to the directory containing Bonita Migration Tool.

  2. Run the migration script:

    • For version 1.x of the migration tool, run migration.sh (or migration.bat for Windows).

    • For version 2.x of the migration tool, go to the bin directory and run the migration script for your edition and operating system:

Community edition

bonita-migration-distrib (Linux) or bonita-migration-distrib.bat (Windows)

Subscription editions

bonita-migration-distrib-sp (Linux) or bonita-migration-distrib-sp.bat (Windows)

Starting from Bonita Migration Tool 2.44.1, an additional script called check-migration-dryrun is present in the same folder. This script only runs the checks the real update would run, without actually migrating the elements. This is equivalent to running the migration script with a --verify option.

Once the script is started

  1. The script detects the current version of Bonita, and displays a list of the versions that you can update to.

  2. Specify the version you require.

  3. The updating procedure starts

  4. As the script runs, it displays messages indicating progress. After each step, you are asked to confirm whether you want to proceed to the next step. You can pause the updating procedure by answering no. To suppress the confirmation questions, so that the update can run unattended, set the ` (-Dauto.accept=true)` system property.

  5. When the migration script is finished, a message is displayed showing the new Runtime version, and the time taken for migrating all the elements. The database has been updated.

Do not use the old Tomcat server: a new one needs to be installed with the Bonita binaries that match the target version.

Setup the target Bonita bundle

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

  2. 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.

  3. Reapply the configuration made to the runtime, using the setup tool of the bonita-target-version

  4. Download the configuration from the database to the local disk.

Below you can find a Linux exemple:

 cd setup
 ./setup.sh pull

You must reapply the configuration that had been done on the original instance’s BONITA_HOME into the bonita-target-version/setup/platform_conf/current ``
Please refer to the guide on updating the configuration file using the 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 at bonita-target-version/server (or bonita-target-version if the target version is Bonita 7.3.n or greater): customization, libs etc.

  • If the source version is Bonita 7.4 or greater: In the case where deployed resources have required dedicated authorizations to use the REST API, these authorizations are not automatically migrated. Some manual operations have to be done on files that are located in the extracted platform_conf/current folder (see Update Bonita Runtime configuration for more information). You need to:

    • Perform a diff between the source version and the target version of tenants/[TENANT_ID]/conf/compound-permissions-mapping.properties and put the additional lines into the file tenants/[TENANT_ID]/conf/compound-permissions-mapping-custom.properties

    • Perform a diff between the source version and the target version of tenants/[TENANT_ID]/conf/resources-permissions-mapping.properties and put the additional lines into the file tenants/[TENANT_ID]/conf/resources-permissions-mapping-custom.properties

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

    • Report all the content of the source version oftenants/[TENANT_ID]/conf/custom-permissions-mapping.properties into the target version.

License

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

Below you can find a Linux exemple:

 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 to request and install a new one:

Install the new license:

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

Start the new Bonita Runtime

  1. Start the application server. Before you start Bonita Applications, clear your browser cache. If you do not clear the cache, you might see old, cached versions of Portal or Applications pages instead of the new versions.

  2. Log in to Bonita UIs and verify that the updating procedure has completed.

  3. If you used Bonita Migration Tool 2.41.1 or greater, the table arch_contract_data is automatically backed up to the table arch_contract_data_backup to avoid long lasting migration. To reintegrate the data into your installation, a new tool is provided in Bonita Migration Tool 2.46.0 and above. It is located in the tools/live-migration folder. Follow instruction in the README.md to run this tool and re-integrate data from arch_contract_data_backup.

  4. The update is now complete.

Special cases

Migrating processes with 6.x forms and case overview pages

Until Bonita 7.0.0, Bonita used UI artifacts based on the Google Web Toolkit (GWT) technology: process instantiation forms, task execution forms and case overview page. The runtime support for those forms and pages was removed in 7.8.0.

It means that if one or more processes on the target server uses 6.x forms or overview page, the migration to a Bonita 7.7.x and greater cannot be performed directly. The following lines explain how to migrate a process to Bonita 7.8.0, for example.

  • If you are updating from a Bonita 6.x version, follow this procedure:

    1. Update to Bonita 7.0.0 using the Migration Tool 1.x.

    2. Update to the last 7.7.x version, using the Migration Tool 2.x.

    3. Redesign your processes to use contracts at process instantiation and task execution levels, and recreate all your forms and case overview pages in Bonita Studio using the UI Designer or your favorite IDE, so that they use contracts. For more information, go to migrate a form from 6.x

    4. Upload the new version of all your processes using contracts, new forms, and new case overview pages.

    5. Make sure the versions of the processes using 6.x forms have no more running instances, and disable them.

    6. Perform the updating procedure to the desired version.

  • If you are updating from a Bonita 7.x version, follow this procedure:

    1. Redesign all your forms in Bonita Studio using the UI Designer. For more information, see how to migrate a form from 6.x

    2. Upload the new versions of all your processes using the new forms

    3. Make sure the versions of your processes using 6.x forms have no more running instances

    4. Disable them

    5. Perform the updating procedure to the desired version

The disabled processes with 6.x forms cannot be enabled again post update.

Case overview pages

Having 6.x case overview pages on your processes will not prevent the update of the runtime. However, they will all be replaced by the default 7.x case overview page, created with the UI Designer. It means that you might want to redo the case overview pages as well as the forms, especially if you have configured a custom case overview page for your processes in version 6.x.
Alternatively, you can also live update the case overview page after the update is complete. (Enterprise, Performance, and Efficiency editions only).

Automated replacement of case overview pages during the updating procedure

If the source version is older than Bonita 7.8.
Starting with Bonita 7.8, Bonita Migration Tool ships an option to allow you to replace 6.x case overview pages with the default 7.x case overview page (created with the UI Designer). This allows you to see if the page suits your needs.
If not, it can be used as a base to customize your case overview page. Your pages will then be ready for the 7.8.0 step of the Bonita Runtime update.

To run this option, unzip the migration tool and execute the following commands:

  • For Community edition:
    ./bonita-migration-distrib (Linux) or bonita-migration-distrib.bat (Windows) --updateCaseOverview <PROCESS_DEFINITION_ID>

  • For Subscription edition:
    ./bonita-migration-distrib-sp (Linux) or bonita-migration-distrib-sp.bat (Windows) --updateCaseOverview <PROCESS_DEFINITION_ID>

For instance:

./bonita-migration-distrib-sp --updateCaseOverview 6437638294854549375

If you want to update several processes, simply run the command with all the processDefinitionId’s one by one.

This tool will only change case overview pages. This means that if some of your processes still have process instantiation / task execution forms, you need to redesign them in Bonita Studio using Bonita UI Designer, as explained in the section above.

Example of output issued when running the tool:

6.x application resources

6.x application resources have been removed in Bonita 7.8.0, so if you are migrating a process that leverages this feature, you need to modify it (for example to use process dependencies instead (Configure > Process dependencies in Bonita Studio)).

Updating to Java 11 in Bonita 7.9 or a greater version

Bonita 7.9 and greater versions support Java 11. Migrating an existing platform to Java 11 is not an easy, or painless endeavour. To migrate a Bonita platform to Java 11, proceed with the following steps:

  1. Update Bonita Runtime to Bonita 7.9.0 as usual, and keep running it in Java 8

  2. Verify that everything works as expected

  3. Test the target Runtime in Java 11, on a test environment

  4. Update what is required on the production server

  5. Switch it to Java 11

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

The 7.9.0 updating step tries its best to update the implementation of connectors that are known not to work in Java 11, namely WebService, CMIS, Email and Twitter.
See [_connector_details_regarding_migration_to_7_9].

On the other hand, custom connectors, groovy scripts, REST API extensions etc. are not migrated and might not work outright in Java 11.

Aside from just code incompatibility, special attention has to be given to the dependencies of the custom code, as they might either not work in Java 11, work fine but conflict with Bonita own dependencies or the script might use dependencies previously included in Bonita, but no more accessible, or accessible in a different version.
Thus, thorough testins has to be carried out to ensure there is no regression when migrating Bonita to version 7.9 and greater.

Updating to Bonita 7.9 or a greater version using PostgreSQL

Bonita 7.9 and greater versions support PostgreSQL 11.x (x>=2) which is not compatible with previous versions. When updating to Bonita 7.9 or a greater version using PostgreSQL, follow this procedure:

  1. Shutdown Bonita

  2. Run the migration tool to the latest Bonita version supporting postgreSQL 9 (7.8.4)

  3. Backup the database

  4. Update PostgreSQL from 9 to 11.x (x>=2) following the Official documentation

  5. Run the migration tool again to the target Bonita version requiring PostgreSQL 11

  6. Restart the new Bonita Runtime

Updating to Bonita 7.9 or a greater version using MySQL

Bonita 7.9 and greater versions support MySQL 8.0.x version, which is not compatible with older versions of MySQL. For this reason, to update to Bonita 7.9 or a greater version when using MySQL, follow this procedure:

  1. Make sure Bonita Runtime is shut down

  2. Run the migration tool to update to Bonita 7.9 or greater, following the procedure above

  3. Update your MySQL database server installation following the official documentation

  4. Restart the new Bonita Runtime

Updating to Bonita 7.9 or a greater version using Oracle

Bonita 7.9 and greater versions support Oracle 12c (12.2.0.x.y) and Oracle 19c (19.3.0.0) versions: this is a requirement change.

The Oracle database server change needs to be done before using the migration tool from Bonita 7.8.4 to Bonita 7.9.0.

Updating to 7.8.4

If the target version is Bonita 7.8.4, skip this section and jump directly to the Update Oracle database server section .

  1. Shut down Bonita Runtime

  2. Run the migration tool to update to Bonita 7.8.4, following the updating procedure above

Update Oracle database server

  1. Shut down Bonita Runtime

  2. Update the Oracle database server to the version 12c (it must be 12.2.0.x.y) or 19c (it must be 19.3.0.0)

Configure the Oracle database server

  1. Configure the Oracle database server, in particular activate the XA transactions management: see the Oracle Database section in the Database creation and configuration for Bonita engine and BDM page

  2. Install the missing Oracle components

  3. Execute the SQL scripts to install XA management elements

  4. Execute the SQL requests to GRANT the proper rights to the Oracle users; for both Bonita BPM and BDM schemas

Download the specific jdbc driver for the Oracle 12c (12.2.0.x.y) or 19c (19.3.0.0)

Caution: two different jdbc driver jar files may share the same name (ojdbc8.jar).

Each file however is specific to the Oracle DB server version installed.
Please make sure to download the appropriate one:

Note: Bonita Migration Tool already includes the Oracle driver for Oracle 19c (19.3.0.0) in the bonita-migration/lib directory. If your are not using Oracle 19c (19.3.0.0) you need to replace it.

Check the Bonita 7.8.4 server starts with the Oracle database server 12c (12.2.0.x.y) or 19c (19.3.0.0)

  1. Download and install a Bonita 7.8.4 bundle

  2. Setup the Bonita 7.8.4 bundle to use the Oracle 12c (12.2.0.x.y) or 19c (19.3.0.0) database

  3. Request and install a temporary 7.8 license in the Bonita bundle

  4. Start the Bonita 7.8.4 bundle

  5. Check that you can successfully log into the Bonita applications.

Update to Bonita 7.9 or a greater version

  1. Shut down Bonita Runtime

  2. Run the migration tool to update to Bonita 7.8.4, following the updating procedure above

  3. Update your Oracle database server to the version 12c (it must be 12.2.x.y)

  4. Run the migration tool again to update Bonita to 7.9 or a greater version

  5. Restart the new Bonita Runtime

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:

  1. Shut down Bonita Runtime

  2. Run the migration tool to update to Bonita 7.10.5, following the procedure above

  3. Update your Oracle database server to version 19c (version 7.10.x is compatible with 12c and 19c.)

  4. Run the migration tool again to update to Bonita 7.11.0 or greater version

  5. 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 between maintenance versions of Bonita in Bonita 7.11 and greater versions

Starting with Bonita 7.11, updating between maintenance versions of the same main version does not require the migration tool. To do so (for example going from Bonita 7.11.0 to 7.11.1), follow the following steps:

  1. Download the new bundle version from Bonitasoft site for Bonita Community edition or from the Customer Service Center for Bonita Subscription editions

  2. Shut down your old Bonita Runtime

  3. 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.

  4. Start the new bundle

  5. 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:

In a cluster environment, you need to stop all your nodes and update them before starting them with the new maintenance version.

  1. Download Bonita Migration Tool:

    • In version 1.x you need to download the tool for Performance cluster, the ordinary Performance migration tool does not support the update of a cluster.

    • In version 2.x there is only one kind of migration tool. It will work for both cluster and non cluster installation.

  2. Shutdown all cluster nodes.

  3. On one node, follow the procedure above to update Bonita Runtime.

  4. When the update is complete on one node, follow steps 12 to 16 on all the other nodes.

The update of the cluster is now complete, and the cluster can be restarted.

Migrate your client applications

If you have applications that are client of Bonita, you may have to change your client code or library. Most of the time, we guarantee backward compatibility. In any case, read the release notes to check if some changes have been introduced.

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

troubleshooting-icon Troubleshooting

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 is no change in Bonita’s behaviour. 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):

First, 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. Migrating to Bonita 7.11.6 or greater versions fixes the issue.

Addendum

Connector details regarding the update to Bonita 7.9

For Bonita 7.9.0, the updating step tries to migrate the CMIS, Email and Webservice connectors of the processes deployed on the platform, along with their dependencies, to allow the updated platform to run on Java 11.
The step works at "best effort":

  • It will try to update all the connectors it can.

  • It will not update connectors that have dependencies used by other connectors. Those connectors will still work on java 8, but not in java 11, and will require a manual update.

  • A detailed report of all the changes made is displayed at the end of the updating step.

  • Beware that if one of these connectors' removed dependencies was used in one your scripts, it will still be removed/updated, and therefore your scripts might not work anymore after the update. The full list of updated and deleted dependencies can be found below.

From Bonita 7.9 and greater versions, the supported version of Oracle database is 12c (12.2.x.y) To update to Bonita 7.9 or a greater version from an earlier version than Oracle 12c (12.2.x.y), see Updating to Bonita 7.9 or greater versions using Oracle.

WebService connector

The following dependencies have been added, to ensure Java 11 compliance:

  • javax.xml.stream:stax-api:1.0-2

  • org.codehaus.woodstox:woodstox-core-asl:4.1.2

  • org.codehaus.woodstox:stax2-api:3.1.1

  • com.sun.istack:istack-commons-runtime:2.4

  • javax.activation:activation:1.1

  • com.sun.xml.messaging.saaj:saaj-impl:1.3.28

  • javax.xml.ws:jaxws-api:2.2.7

  • com.sun.xml.ws:jaxws-rt:2.2.7

  • javax.jws:jsr181-api:1.0-MR1

  • javax.xml.bind:jaxb-api

  • com.sun.xml.bind:jaxb-impl

CMIS connector

The following dependencies were updated to ensure Java 11 compliance:

  • org.apache.chemistry.opencmis:chemistry-opencmis-client-impl dependency has been updated from 0.13.0 to 1.1.0

  • org.apache.chemistry.opencmis:chemistry-opencmis-client-api dependency has been updated from 0.13.0 to 1.1.0

  • org.apache.chemistry.opencmis:chemistry-opencmis-commons-api dependency has been updated from 0.11.0 to 1.1.0

  • org.apache.chemistry.opencmis:chemistry-opencmis-commons-impl dependency has been updated from 0.11.0 to 1.1.0

  • org.apache.chemistry.opencmis:chemistry-opencmis-client-bindings dependency has been updated from 0.11.0 to 1.1.0

  • org.apache.cxf:cxf-rt-bindings-xml dependency has been updated from 2.7.7 to 3.0.12

  • org.apache.cxf:cxf-rt-frontend-simple dependency has been updated from 2.7.7 to 3.0.12

  • org.apache.cxf:cxf-rt-core dependency dependency has been updated from 2.7.7 to 3.0.12

  • org.apache.cxf:cxf-rt-transports-http dependency has been updated from 2.7.7 to 3.0.12

  • org.apache.cxf:cxf-rt-ws-policy dependency has been updated from 2.7.7 to 3.0.12

  • org.apache.cxf:cxf-rt-ws-addr dependency has been updated from 2.7.7 to 3.0.12

  • org.apache.cxf:cxf-rt-bindings-soap dependency has been updated from 2.7.7 to 3.0.12

  • org.apache.cxf:cxf-rt-databinding-jaxb dependency has been updated from 2.7.7 to 3.0.12

  • org.apache.cxf:cxf-rt-frontend-jaxws dependency has been updated from 2.7.7 to 3.0.12

  • org.apache.neethi:neethi dependency has been updated from 3.0.2 to 3.0.3

  • org.apache.ws.xmlschema:xmlschema-core dependency has been updated from 2.0.3 to 2.2.1

The following dependencies have been added to ensure Java 11 compliance:

  • org.apache.cxf:cxf-rt-wsdl-3.0.12

The following dependencies have been removed:

  • org.jvnet.mimepull:mimepull-1.9.4.jar

  • org.codehaus.woodstox:stax2-api-3.1.1.jar

  • org.apache.geronimo.javamail:geronimo-javamail_1.4_spec-1.7.1.jar

  • org.codehaus.woodstox:woodstox-core-asl-4.2.0.jar

  • org.apache.cxf:cxf-api-2.7.7.jar

In addition bonita-connector-cmis-<version>.jar and bonita-connector-cmis-common-<version>.jar have been replaced by a single bonita-connector-cmis-<version>.jar

Email connector

The version of the javax.mail:mail dependency has been updated from 1.4.5 to 1.4.7

Twitter connector

The version of the org.twitter4j:twitter4j-core dependency has been updated from 4.0.2 to 4.0.7