How to manage a BDM update

We recently described the improvements in the Business data model (BDM) in Bonita 2021.2, that make it easier for administrators to handle errors and deployment.

If you need to update a BDM in production, some changes can be handled automatically thanks to data persistence managed by Hibernate. For example, adding a new Object (table) or adding a new attribute on an existing Object (new column on an existing database table) are fully supported.

However, some changes have to be made manually. In this article we will list these cases and share best practices to address them.

Changes not supported by data persistence

The following changes will lead to failure when instantiating new objects, although no error will be thrown at BDM update:

• Deleting an object (table)
• Deleting a column
• Deleting an index
• Deleting a unique constraint
• Changing the type of an attribute
• Changing the max size of a string attribute
• Changing an attribute from a single type to multiple, for simple types
• Changing an attribute from a multiple type to single, for simple types

The following modifications, on the other hand, will raise an error at BDM update and all BDM schema changes will be rolled back:

• Adding a new object with the same name as a deleted object, but with different attributes
• Making a column "mandatory", deleting a "mandatory" column, or creating a new "mandatory" column
• Adding or deleting a new unique constraint
• Changing an object attribute from a single type to a multiple type
• Changing an object attribute from a multiple type to a single type

How to prevent issues with the data model

For any update in the above list, you will have to perform some manual actions.

We strongly recommend that you first test the BDM update in a staging environment and that you back-up your database prior to any update.

Here are the steps:

1. Prepare the BDM schema update
   1. The easiest way to do it is to first install your new BDM on a clean database.
   2. Then compare the new schema with the old one, and manually create a SQL script to update your BDM database to match the new one.
2. Stop your tenant services
3. Stop your Bonita server
4. Ask your database administrator to update manually the BDM schema in your BDM database to make it correspond to your new BDM.
   1. Apply this SQL script to your BDM database
5. Restart your Bonita server
6. Install your new BDM the usual way
7. Restart your tenant services

All details are described in the official documentation.