Upgrade 11.2 to 12.0

These pages cover the steps required to upgrade a project based on Bloomreach Experience Manager 11.2 to Bloomreach Experience Manager 12.0. A prerequisite for upgrading your project is that you first upgrade to the latest 11.2 version available. Upgrades from earlier versions to 12.0 are only supported when first upgrading to 11.2, and then to 12.0. Before upgrading a project, check the release notes section for the latest version of the Bloomreach Experience Manager 12 range. The latest 12.x version is the preferred version, unless noted otherwise.

Also, take note of the System Requirements and Significant Changes first before starting the upgrade.

The upgrade procedure can be divided into five phases:

1. Get acquainted with Bloomreach Experience Manager 12's Configuration Management mechanism
2. Upgrade the project's sources
3. Locally verify the upgrade against a production repository
4. Locally upgrade a development repository
5. Locally upgrade a production repository

Step 1: Get acquainted with CMS 12's Configuration Management mechanism

At the heart of the upgrade to CMS 12 is the new Configuration Management mechanism. This mechanism requires that the project's bootstrap resources are migrated from the old XML format to the new YAML format.

Therefore, before rushing into a first upgrade attempt, please take sufficient time to study and familiarize yourself with the new mechanisms and formats. Apart from our online documentation, we describe how to use the configuration management concepts in the context of the upgrade to Bloomreach Experience Manager 12. Also, please consider playing with a fresh, archetype-based Hippo project, or study how our community test project uses the new mechanisms.

Step 2: Upgrade the project's sources

The steps for upgrading the project's source code are as follows.

1. Replace all deprecated Java code. Deprecated code may have been dropped in Bloomreach Experience Manager 12, and your code may therefore no longer compile. To make sure your changes didn't break anything, you may want to build, run and test your changed Bloomreach Experience Manager 11 project.
2. Upgrade Project Files.
3. Upgrade the CMS
4. Upgrade HST
5. Migrate from log4j to log4j2
6. Migrate XML bootstrap resources to YAML
7. Upgrade URL Rewriter (if used)
8. Upgrade Auto-Export Configuration
9. Migrate HST channels
10. Upgrade security group provider
11. Consolidate Webfiles
12. Revisit CMS Users
13. Upgrade Enterprise Forms (if used)

Now, you should be able to successfully build the web application(s) of your project, and to start them locally, bootstrapping a fresh repository. Make sure that there are no unexpected or undesired log messages, and that your project's custom functionality is working as it should and used to.

Step 3: Locally verify the upgrade against a production repository

Bloomreach has created the Configuration Verifier tool to assist in the validation of an upgrade to Bloomreach Experience Manager 12. Upon completion of the upgrade of the Bloomreach Experience Manager project, the tool is used to simulate the upgrade of a Bloomreach Experience Manager 11.2 repository. Its output is a list of configuration changes (deltas) that will be applied to the repository, if you would deploy the upgraded project as is. These changes need to be examined to make sure that all of them are valid and desired. Undesired (loss of) changes can be eliminated by incorporating them into your project's YAML config (or content) definitions. You can re-run the tool as many times as needed, until you are happy with the result, and ready to upgrade a local copy of a repository.

Set up a copy of the production database

Request a recent production database dump from the system administrator and import it into a local database server. For MySQL, the typical steps for this are as follows:

$ mysql -u username -p -e"create database myhippoproject"
$ mysql -u username -p --database myhippoproject < myhippoproject.sql

The latter command might take a while to finish, depending on the size of the database.

Set up your project to use this database by following Use MySQL in a Development Environment, and make sure to use a clean repository storage directory as configured through the -Drepo.path=<absolute folder location> parameter.

Verify the upgraded project configuration

Now follow the Configuration Verifier Usage and Resolving Configuration Verifier Deltas instructions to validate your project configuration is upgraded as expected and intended. 

Step 4: Locally upgrade a development repository

Before doing an upgrade of a copy of a full production repository (which might take some time), we recommend a more light-weight validation first:

1. Check out (in a separate folder) the pre-upgrade version (e.g. version 11.2) of your project, and bootstrap a fresh repository (based on your old XML bootstrap resources). After successful bootstrapping, shut down your project.
2. Copy that repository (located where your repo.path system property pointed to, or target/storage by default) into your upgraded project.
3. Start the upgraded project, pointing repo.path to the repository you just created for the pre-upgraded .
4. Verify that the project starts successfully, and all features of your project are operational. Fix any startup or runtime issues and go back to step 2.

Step 5: Locally upgrade a production repository

As a last validation before starting to deploy the upgraded project into your DTAP street, you should locally upgrade a (recent) copy of a production repository.

You can reuse the production database setup for Step 3, or if there are (potentially) significant changes to the production database, request a new/latest production database dump to do so again.  

Start up your project

Now start your project, and make sure to use (again) a clean repository storage directory if you imported a new copy of the production repository database.

$ mvn -Pcargo.run -Drepo.path=/tmp/myrepo

Depending on the number of nodes in the repository, starting up might take a while, mostly due to the Lucene index creation.

During startup check all logs and make sure to process all WARN and ERROR messages and if needed take action. 

Validate the upgraded project

When validating the upgrade of a development repository (step 4), you have already converged to a sensible Configuration Model. This validation step should primarily focus on examining how the upgrade interacted with the content part of the repository, such as the documents, modifiable HST configuration, URL rewriting rules etc. Also, if you, in step 3, decided not to reintegrate some runtime changes on production into your project's config definitions in order to revert it, validate that the runtime change(s) have indeed been reverted.

Once the upgraded project starts up correctly against a production repository, you can deploy to test, acceptance, and production environments.

For upgrading clustered production environments, we recommend starting a new cluster with a database copy, and upgrade this cluster. After the upgraded cluster works correctly, switch visitors to the new cluster. A Content Freeze will have to be appointed with your CMS users during this period.