This documentation is about a version that is out of support, here is the latest documentation version.

How about downloading a newer, supported version?

Updating Bonita Runtime with Migration Tool

Service stopped: Migrate the data, install a new environment, test non-migrated elements behavior and compatibility with new bonita version

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 your Bonita Runtime to a newer version. Short procedure : Service stopped, migrate the data, install a new environment, test non-migrated elements behavior and compatibility with new bonita version. Detailed procedure : Updating Bonita bundle: step-by-step procedure.

There are 2 versions of Bonita Migration tool:

Tool

Use cases

Bonita Migration Tool 1.x

From version 6.0.2 or later to any version up to 7.0.0

Bonita Migration Tool 2.x

From version 7.0.0 or later to any version up to 7.13.0

WARNING : 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 Bonita Migration Tool 1.x, and then update from Bonita 7.0.0 to Bonita 7.1.0 using Bonita Migration Tool 2.x.

You are NOT recommended to start Bonita 7.0.0 after you update to it, but to continue with the second phase of the update process.

How does Bonita Migration Tool work?

Bonita Migration Tool contains a set of scripts that execute changes on the data for making it compatible with a newer 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 maintenance version being equal to a step. The script manages the sequence of steps from your current version to the targeted version. After each main or maintenance version update

Can the Migration Tool be used for upgrade/downgrade between community and subscription?

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

Bonita version to target

Always update to the latest maintenance release version of the chosen main release. 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:
  • Do not pause the BPM Services before the update. 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.

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

  • 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.9.y to 7.10.0, you will need to read all the release notes in between those versions.

  • Go through the [Special cases] and [Troubleshooting] paragraphs below.

  • Runtime tomcat server custom configuration: You will need to re-apply your customizations after the update process finishes.

  • Runtime setup folder custom configuration 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.

  • If you are updating from a version lower than 7.3, see special cases Update from a Bonita version lower than 7.3 section below.

  • Process definition sources (.bos files) require a manual update. First export then import them into the new Bonita Studio version.

  • 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 to the 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.

  • Check that the database version is up-to-date and supported by the new Bonita version.

  • Secure the update by doing backups. Better safe than sorry.

When the script has finished executing, you will have to complete the update procedure by unzipping and configuring new version’s bundle. Go through the paragraph Updating Bonita bundle: step-by-step procedure for step-by-step instructions.

BACKUPS

Configuration files

As mentioned above, unless you are updating from a version lower than 7.3, Bonita configuration files 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:

There is below a Linux example:

cd setup
./setup.sh pull

If you are updating from a version lower than 7.3, see special cases Update from a Bonita version lower than 7.3 section below.

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.

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 7

If targeting an update from Bonita 7.0 to 7.4.x

JRE version 8

If targeting an update from Bonita 7.5 to Bonita 2021.1-0811

JRE version 11

If targeting an update from Bonita 2021.2 or greater

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

RDBMS requirements: The version targeted may not support the version of the database that is being migrated. You may then need to upgrade the version of your database prior to running the Bonita Migration Tool.

Community/Subscription edition: The tool updates your platform (bonita_home folder and the database). You cannot change edition while updating.

  • If you are running a Bonita Subscription Pack edition, you need a valid license for your target version.

  • If you are upgrading to a new maintenance version and not changing the minor version number (for example, you are updating from x.y.0 to x.y.1), your current license remains valid after update.

Starting from version 7.3 there is no more bonita home folder. This means that, if you are updating from a version lower than 7.3 AND if your installation does not have any custom bonita home or server configurations, then you do not need to configure the bundle any further for an installation updated in 7.3 or above.

On the other hand, if you are updating from a version lower than 7.3 AND you have customized your bonita home folder or server configuration, you will have to use the platform setup tool to pull the default configuration from the database where configuration is stored, then re-apply your customized configuration in the files that you’ve pulled from the database, and finally use the platform setup tool to push your custom configuration in the database. You will also need to re-apply the specific configuration you might have made in the application server files. See special cases Update from a Bonita version lower than 7.3 section below.

Update steps

How it works

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

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

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

  • Runtime data in Bonita Home, until 7.3

  • Log files from the previous version are not impacted by update

The following are not updated automatically:

  • Configuration: 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. If your previous version is lower than 7.3, see special cases Update from a Bonita version lower than 7.3 section below.

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

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

  • Business data model, and the business data database: if the update path include version 7.0.0,7.2.0 or 7.2.4, the Business data model must be redeployed after update. Only in that case, can you pause the tenant before update, as a tenant admin, so that you’ll be able to redeploy the BDM on a paused tenant once update is done, using Define and deploy the BDM). 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.

  • Custom reports: 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.

When the script has finished, you need to complete the update by unzipping and configuring a bundle for the new version. See Update your platform for step-by-step instructions.

Constraints

  • 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 be complete.

  • There is no guarantee that the Look & Feel definition is compatible across maintenance versions. For example, in 6.2.2, jquery+ was renamed jqueryplus in BonitaConsole.html, for compatibility with more application servers. If you are using a custom Look & Feel, export it before updating. Then after the update process is complete, export the default Look & Feel from the new version, modify your custom Look & Feel to be compatible with the new definition, and with the recommendations for form footers. Then import your updated custom Look & Feel into Bonita Portal.

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

Important:
You must do a backup of your configuration files before starting the update.
You might need to merge custom properties and configurations to the updated environment.

Furthermore, from the database point of view, as any operations on a production system, updating is not a zero risk operation.
Therefore, it is strongly recommended to do a backup of your database before starting the update process.

Estimate time required

The platform must be shut down during 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 the time that will be required. 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

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

  1. Download the target version bundle and the Bonita Migration Tool for your Edition from the Bonitasoft site for Bonita Community edition or from the Customer Service Center for Bonita Subscription Pack editions.

  2. Check your current RDBMS version is compliant with the versions supported by the target version of Bonita (see above)

  3. Unzip the Bonita Migration Tool zip file into a directory. In the steps below, this directory is called bonita-migration.

  4. If you use Oracle, there is already the driver for 19.3.0.0 oracle version in the bonita-migration/lib. add the JDBC driver for your database to bonita-migration/lib. This is the same driver as you have installed in your web server lib directory. You must upgrade to Oracle 12c (12.2.x.y) in order to update to 7.9+.

make sure you double check that you use the official driver version that match your Database version. The correct driver is mandatory for a smooth migration: Follow instructions for Oracle driver download. Particularly, if you use Oracle 12.2.0.x.y and are migrating to 7.9.n or to 7.10.n, then remove the existing ojdbc8-19.3.0.0.jar file, and add the specific JDBC driver to bonita-migration/lib.
  1. If you use Microsoft SQL Server, add the JDBC driver for your database type to bonita-migration/lib. This is the same driver as you have installed in your web server lib directory.

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

    Property Description Example

    bonita.home

    The location of the existing bonita_home. Required only until 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_migration

    db.user

    The username used to authenticate to the database

    bonita

    db.password

    The password used to authenticate to the database

    bpm

Note: If you are using MySQL, add ?allowMultiQueries=true to the URL. For example, db.url=jdbc:mysql://localhost:3306/bonita_migration?allowMultiQueries=true.
Also, if you are updating to Bonita 7.9+, you must upgrade your database server to MySQL 8.0, see Updating to Bonita 7.9+ using MySQL specific procedure below.

  1. If you use a custom Look & Feel, export it, and then restore the default Look & Feel.

  2. If you use a Business data model that requires to be redeployed (see above), you can pause the tenant so that as a tenant admin, you’ll be able to redeploy the BDM on a paused tenant once update process is done. If your update path does not include version 7.0.0,7.2.0 or 7.2.4, you don’t need to redeploy the Business data model, so do not pause the tenant.

IMPORTANT: Do not pause the BPM services before you stop the application server. It will cause problems.

  1. Stop the application server.

  2. IMPORTANT: Back up your platform and database in case of problems during update.

  3. Go to the directory containing the Bonita Migration Tool.

  4. Run the appropriate update script:

Version

Edition

Script

Bonita Migration Tool 1.x

  • migration.sh

  • migration.bat (Windows)

Bonita Migration Tool 2.x

Community edition

  • bonita-migration-distrib (Linux)

  • bonita-migration-distrib.bat (Windows)

Bonita Migration Tool 2.x

Subscription editions

  • bonita-migration-distrib-sp (Linux)

  • bonita-migration-distrib-sp.bat (Windows)

  • Starting from version 2.44.1, an additional script called check-migration-dryrun is present in the same folder. 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 migration script with a --verify option.

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

    2. 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, the time taken for updating all the elements will be mentioned in a dedicated user message.

Do not use the old application server: a new one needs to be installed with the Bonita binaries that match the target version.
  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 migrated 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 migrated database.
  3. 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
  4. If you are updating from a version lower than 7.3, see special cases Update from a Bonita version lower than 7.3 section below.

  5. 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
  6. If you have done specific configuration and customization in your server original version, re-do it by configuring the application server at bonita-target-version/server (or bonita-target-version if target version is 7.3.n): customization, libs etc.

  7. If your Bonita version is 7.4 or above before updating, you can skip this point. In the case where deployed resources have required dedicated authorizations to use the REST API, these authorizations are not automatically updated. Some manual operations have to be done on files that are located in the extracted platform_conf/current folder (see Update Bonita Platform configuration for more information). You need to:

    • Perform a difference check between the versions before and after update 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 difference check between the versions before and after update 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 difference check between the versions before and after update of 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 version before update oftenants/[TENANT_ID]/conf/custom-permissions-mapping.properties into the new version.

  8. Configure License:

    you need to put a new license in the database: see Platform configuration for further details. There is below a Linux example:

    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
  9. Start the application server. Before you start Bonita Portal, clear your browser cache. If you do not clear the cache, you might see old, cached versions of Portal pages instead of the new version. Log in to the Portal and verify that the update process has completed. If you did not set the default Look & Feel before update and you cannot log in, you need to restore the default Look & Feel using a REST client or the Engine API.

  10. If you update to a later version than 7.7 In that case, if you used the 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 update. To reintegrate the data into your installation, a new tool is provided in versions 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.

The update is now complete. If you were using a custom Look & Feel before updating, test it on the new version before applying it to your updated platform.

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

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

From a Bonita 6.x version

From a Bonita 7.x version

  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.

  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

Having 6.x case overview pages on your processes will not prevent updating the platform, 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 page as well as the forms, especially if you have configured a custom case overview page for your processes in version 6.x. Or (for Enterprise, Performance, and Efficiency editions only), you can live update it after update.

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

Updating from a Bonita version lower than 7.3

Starting from version 7.3 there is no more bonita home folder. This means that, you will need to manually re-do all the configuration and customization that used to be stored in your bonita home folder and in your server original version.

When updating from a version lower than 7.3, after the you run the migration tool, the default configuration files of the new version will be pushed in the database.

Therefore, if your installation didn’t have any custom changes in the bonita home folder, then you do not need to configure the bundle any further for an installation migrated in 7.3+ or greater.

On the other hand, if you had customized your configuration in the bonita home folder, you will have to use the platform setup tool to update the default configuration and apply yours to push it in the database where configuration is now stored.

Here’s how to reapply configuration made to the platform, using the setup tool of the bonita-target-version:

  1. 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
  2. You must reapply the configuration that had been done on the original bonita home folder into the bonita-target-version/setup/platform_conf/current. Please refer to the guide on updating the configuration file using the platform setup tool

Some manual operation have to be done on files that are located in the bonita home folder if version <7.3.0 or in the extracted platform_conf/current folder in version >=7.3.0. You need to merge the previous file version and the migrated one:

  1. In the case where deployed resources have required dedicated authorizations to use the REST API, these authorizations are not automatically migrated.

tenants/[TENANT_ID]/conf/compound-permissions-mapping.properties : contains list of permissions used for each resources

tenants/[TENANT_ID]/conf/resources-permissions-mapping.properties : contains permissions for REST API extensions

tenants/[TENANT_ID]/conf/custom-permissions-mapping.properties : contains custom permissions for users and profiles

tenants/[TENANT_ID]/conf/dynamic-permissions-checks.properties : used if dynamic check on permissions is enabled

You will have to reapply this configuration in the same files in /setup/platform_conf/current/tenants/[TENANT_ID]/tenant_portal/ folder.

  1. When done, push the updated configuration into the database:

    ./setup.sh push
  2. If you have done specific configuration and customization in your server original version, re-do it by configuring the application server in bonita-target-version folder if target version is 7.3.n: customization, libs, transaction default timeout, etc.

Use the provided Bonita tool to update case overview pages before updating to 7.8.0

Bonita Migration Tool now 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), when your Bonita runtime is still in a pre-7.8.0 version. This allows you to see if the page suits your needs, or 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 update step.

To run it, unzip the latest Bonita Migration Tool and run, for Community edition:
./bonita-migration-distrib (Linux) or bonita-migration-distrib.bat (Windows) --updateCaseOverview <PROCESS_DEFINITION_ID>

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

Note: 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 the Studio using Bonita UI designer, as explained in the section above.

Example of output issued when running the tool:

Updating to Java 11 in Bonita 7.9

Bonita 7.9+ supports Java 11. Updating an existing platform to Java 11 is not an easy, or painless endeavour. To update a Bonita platform to Java 11, you need to follow the following steps:

  • Update the platform to Bonita 7.9.0 as usual, and keep running it in Java 8. Verify that everything works as expected.

  • Test the updated platform in Java 11, on a test environment.

  • Once tested, update what is required on the production server, and switch it to Java 11.

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

The 7.9.0 update 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 updated 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 tests have to be carried out so ensure there is no regression when updating Bonita to version 7.9+.

Updating to Bonita 7.9+ using PostgreSQL

Bonita 7.9+ supports PostgreSQL 11.x (x>=2) which is not compatible with previous versions. When updating to Bonita 7.9+ using PostgreSQL follow this procedure:

  • shutdown Bonita

  • Run Bonita Migration Tool to the latest Bonita version supporting postgres 9 (7.8.4)

  • Backup the Bonita database

  • Migrate PostgreSQL from 9 to 11.x (x>=2) following the [Official documentation] (https://www.postgresql.org/docs/11/upgrading.html)

  • Run again the Bonita Migration Tool to the desired Bonita version requiring PostgreSQL 11

  • Restart your updated Bonita platform

Updating to Bonita 7.9+ using MySQL

Bonita 7.9+ supports MySQL 8.0.x version, which is not compatible with older versions of MySQL. For this reason, to update to Bonita 7.9+ when using MySQL, please follow this procedure:

  • ensure your Bonita platform is shut down

  • run Bonita Migration Tool to update Bonita platform to version 7.9 or newer, following the procedure above

  • upgrade your MySQL database server installation following the official documentation

  • once done, you can restart your updated Bonita platform

Update to Bonita 7.9+ using Oracle

Bonita 7.9+ supports 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 Bonita Migration Tool from 7.8.4 to 7.9.0.

Update to 7.8.4

Skip this section and jump directly to Upgrade Oracle database server section if the 7.8.4 is already the version in use.

  • shut down the Bonita platform

  • run Bonita Migration Tool to update Bonita platform to version 7.8.4, following the update procedure above

Upgrade Oracle database server

  • shut down the Bonita platform

  • upgrade 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

  • 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

  • install the missing Oracle components

  • execute the SQL scripts to install XA management elements

  • 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)

Beware: 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 I: The 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)

  • download and install a Bonita 7.8.4 server

  • setup the Bonita 7.8.4 server to use the Oracle 12c (12.2.0.x.y) or 19c (19.3.0.0) database

  • request and install a temporary 7.8 license in the Bonita server

  • start the Bonita 7.8.4 server

  • check you can successfully log into the portal

Update to 7.9+

  • shut down the Bonita platform

  • run the Bonita Migration <tool to update the platform to 7.9+, following the update procedure above

  • then upgrade your Oracle database server to the version 12c (it must be 12.2.x.y)

  • in a second step, run the Bonita Migration Tool again to update the platform to 7.9.0 or newer

  • once done, you can restart your updated Bonita platform

Update your cluster

A Bonita cluster must have the same version of Bonita on all nodes. To update a cluster:

  1. Download the Bonita Migration Tool:

    • If you use Bonita Migration Tool 1.x you must download the tool for Performance cluster, the ordinary Performance migration tool does not support cluster update.

    • Otherwise, use Bonita Migration Tool 2.x.

  2. Shutdown all cluster nodes.

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

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

Cluster update process 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 cases, please read the release notes to check if some changes have been introduced.

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

Troubleshooting

Timers are stuck after updating to 7.10.0+

Symptom: When updating to 7.10.0+ the timers on processes don’t work anymore.

Cause: Bug in the pause/resume of tenant services, fixed in 7.12.1 version. This issue happens because the BPM services were paused before the update was performed.

Solution: If the BPM services were paused before updating or had to be paused for whatever reason, then to resolve this, you need to execute the following database requests after the update process completes and before you restart your Bonita platform:

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.

Addendum

Connector details regarding update to 7.9

For Bonita 7.9.0, the update 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 upgrade all the connectors it can.

  • It will not upgrade 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 update 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 update. The full list of updated and deleted dependencies can be found below.

From Bonita 7.9+, the supported version of Oracle database is 12c (12.2.x.y) To update to Bonita 7.9+ from an earlier version than Oracle 12c (12.2.x.y), see Updating to Bonita 7.9+ 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-.jar and bonita-connector-cmis-common-.jar have been replaced by a single bonita-connector-cmis-.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