Introduction to Bloomreach Experience Manager Upgrades

In order to take advantage of improved code and new features, you should upgrade your Bloomreach Experience Manager project regularly.

Major Upgrade vs. Minor Upgrade

Bloomreach distinguishes between major upgrades and minor upgrades. 

By major upgrade, we mean to deploy a new version of your Bloomreach Experience Manager project, which uses a newer Bloomreach Experience Manager release with a major version number larger than the one currently deployed (e.g.from 13.4 to 14.0).

By minor upgrade, we mean to deploy a new version of your Bloomreach Experience Manager project, which uses a newer Bloomreach Experience Manager release with a minor version number larger than the one currently deployed (e.g. 13.3 to 13.4) or a patch version number larger than the one currently deployed (e.g. 13.4.3 to 13.4.4).

While Bloomreach makes sure that minor upgrades are backwards compatible, providing you with bug fixes and minor improvements only, major upgrades require more attention from Bloomreach Experience Manager developers. During a major upgrade your environment, project code and project configuration may need to change.

For a minor upgrade, in general it is sufficient to follow the generic instructions for minor upgrades.

Deployment wise, for a major upgrade only a stop/start deployment model is supported, meaning that all cluster nodes must be stopped before any nodes of the new major version are started. 

System Requirements

The system requirements can change for major releases. Verify your system and infrastructure matches the requirements when planning an upgrade.

Configuration Verifier

To support Bloomreach Experience Manager customers and partners in upgrading their implementations, Bloomreach provides the Configuration Verifier tool as part of every Bloomreach Experience Manager release. The Configuration Verifier can (and should) be used both before and while performing the upgrade steps, which are explained in detail further below.
The Configuration Verifier assists in validating and comparing the current project's (to be) bootstraped configuration against an already configured repository (database), without actually applying the possible changes but instead just reporting these, making a developer aware of those changes and if needed fix/correct unintended changes before they get deployed and applied in production.

Fitness for Upgrade

Keeping your project fit for upgrades lowers the cost and risk associated with upgrading your Bloomreach Experience Manager project. In addition, upgrading regularly helps obtaining (and maintaining) the knowledge necessary to efficiently and successfully upgrade your Bloomreach Experience Manager project.

The "fitness for upgrade" of your project covers two main areas:

1. The project sources
2. The project configuration

These two areas are described in more detail down below. In order to keep the risk associated with upgrading low, we also recommend that you do not combine the development and deployment of new features with an upgrade. It may even be beneficial to prepare an upgrade by developing and deploying a project version which is fitter for upgrade than what was deployed before.

Project sources

In order to keep your project sources fit for upgrade, consider the following:

• Keep the foot-print of your project small, the less code you have, the less code you need to upgrade. Avoid unnecessary complexity and code duplication. Remove unused (or no longer used) code and resources, your VCS remembers them for you.
• Avoid using deprecated classes.
• Avoid code forks. If you can't implement a feature without forking Bloomreach Experience Manager code, get in touch with Bloomreach and see if there are other ways to accomplish your goal. Also, Bloomreach may be willing to extend the CMS to enable you to implement the desired functionality in a fork-free way.
• When you can't avoid forking, document the exact version and origin of the forked code, as well as the reason behind the forking. Some forks are of a temporary nature (intent). Document the conditions under which a fork can be abandoned, refer to JIRA issues if applicable.
• Keep your repository data well-organized. Be careful including data which may mess up your production content or configuration.
• Use Maven dependency version overriding sparingly, regularly check if your overrides are still necessary, and remove them if not. If you need to override a dependency version, document why you're doing so. This will come in handy when removing the overridden version later on.

Project Configuration

Your project configuration is primarily stored in the JCR repository. While your sources are "safely" packaged inside the deployed WAR, your project's configuration can change at runtime. An upgrade may cause overwriting (or even deleting) parts of your runtime project configuration. Unless your project-specific configuration changes (or extensions) are properly included in your project's repository data, you run the risk of losing them during an upgrade.

For example, consider the situation where you deployed a new version of your project, which includes a new feature. A week after the deployment, you notice that some parameter, controlling the behavior of your new feature, should be adjusted. Luckily, you expose that parameter through a property of some configuration node in your JCR repository. You use the Bloomreach Experience Manager Console to adjust that property, and you're done. - No, not yet. The configuration source for your project still contains the old value, and if a future upgrade happens to reapply that property, your desired value will be lost. To avoid this, you also need to incorporate your runtime configuration changes into your project configuration sources!

As a Bloomreach Experience Manager developer, you're probably used to tweaking a project's configuration through the Bloomreach Experience Manager Console. Adjustments are made quickly, and it is easy to forget incorporating them into your project's configuration sources (unless you do so during development itself with AutoExport enabled). The Configuration Verifier, already mentioned above, can assist with discovering such runtime configuration changes. Not only during a major product upgrade, but as desired at any time, including during (before) regular project updates and deployments! 

Testing the Upgrade

After an upgrade, you want to make sure that all of your project's features are still working as intended. Therefore, the Fitness for Testing of your project also contributes to the Fitness for Upgrade. The effort to test all features can be quite extensive, certainly if the knowledge of what features are included in the project, how they are supposed to work and how they can be tested has faded or is lost. For this reason, having a set of automated end-to-end tests covering the relevant features of your project is of utmost value. Such a set of tests both documents and proves the (in)correctness of the project's features.

If you have to resort to manual testing, you will value a dedicated set of content and configuration for testing the features in a development environment. The set should be small to avoid unnecessarily long bootstrap times, but large enough to support testing all features. Place resources to bootstrap the test content and configuration into a separate Maven module such that you can easily include (or exclude) it from your project. Typically, you don't want to encounter this data on your production system.

Generally necessary upgrade steps

Step 1: Verify and reconcile possible current runtime configuration changes

Before starting with the upgrade process, you must make sure that any current runtime configuration changes are first merged back into your project configuration sources.

The Configuration Verifier can (should) be used for this step, and is described as the 1st scenario/use-case of its Using a production repository database section.

Practically, this means that you should run the Configuration Verifier against the project version source tree, which is currently used in production, and against a most recent backup of the production repository database. See the Configuration Verifier documentation for details on how to set that up.

Then, reconcile and merge any (relevant) runtime production configuration changes into your project source tree (e.g. the 'master' branch) as a new baseline before starting with the real upgrade work and changes.

Step 1.a: Update to the latest Bloomreach Experience Manager (minor and patch) release of the currently used major version

If not done already, always ensure to be updated to the latest available release before starting the upgrade steps to the next major release. For example, if the project is still based on v13.3.0, then first update to v13.4.1 (if that is the latest).

Although minor (and certainly patch) release updates should be backwards compatible, there still may be some important update notes to be taken into account, so make sure to study these notes.

Step 2: Create and backup a local upgrade baseline repository database

Once step 1 is completed, the resulting updated project baseline sources are still on the previous product (major) version. Build and start the updated project baseline to cleanly create a new local (development) repository database. This database will be needed and used after the actual upgrade work (Step 4) to compare and verify the resulting configuration (Step 5), before doing this 'for real' against a production database in Step 7.

When possible, using a local H2 database (as configured by default) is most convenient for this purpose as it is easy to copy and backup on filesystem level (e.g. just copy everything stored under the default target/storage location). Make sure to backup/label the database appropriately. Step 5 will refer to this as the baseline repository.

Step 3: Catch-up with the target version documentation and upgrade instructions

Make sure to have read the overview of the Significant Changes and generally relevant documentation specific to the target Bloomreach Experience Manager version, as well as the version-specific Upgrade Steps instructions.

Step 4: Upgrade the project sources (code and configuration)

The target version specific Upgrade Steps will provide the necessary details for this phase.

Remove or replace any classes that are deprecated in the target version.

Once the necessary changes have been applied, make sure (and test) the project at least can be started locally without bootstrap errors (some warnings may still be OK at this stage), using a new (empty) repository database.

Step 5: Verify the upgraded project configuration against the local baseline repository

This step assumes a local baseline repository has been created in Step 2 using the baseline project sources (from before the upgrade changes made in step 4).

Furthermore, it assumes (and requires) that the updated project can minimally be started without bootstrap errors.

Then it is time to verify the upgraded project configuration against the "before upgrade" baseline repository, using the Configuration Verifier as described in its Using a development repository database section.

Running the Configuration Verifier now against a development baseline repository will help identify possibly overlooked (or otherwise unexpected) impactful configuration changes, which if not corrected, may cause functional errors as well as possibly configuration data loss in production!

Make sure to validate and accept (or explicitly ignore) all the configuration changes reported by the Configuration.

Step 6: Test the running upgraded project on technical and functional level locally

This step and tests needed is project-specific, but as far as possible and feasible, this step should be done thoroughly and as much as possible automated.

Proceed with the next and final step, before moving on with an acceptance (test) release and deployment of the updated project, once these local or development level tests have been completed successfully.

Step 7: Verify the upgraded project configuration against the local baseline repository

This is the final (developer) step in the upgrade process.

Now the Configuration Verifier should be (re)executed against a most recent/latest production repository database, to ensure and verify there will be no (new) unexpected configuration changes once the upgraded project is deployed.

This is similar to the effort in step 1, but in this case to verify the configuration changes as result of the upgrade, instead of reconciling changes in the production runtime repository.

The instructions also are similar, described for this case as the 2nd scenario in the Using a production repository database section.

Finishing the upgrade

What remains to be done after the above steps is the actual release (e.g. tagging) of the project sources and the deployment to an acceptance environment to verify the expected behavior. And thereafter the final deployment to the production environment.