Upgrade 13.0 to 13.1

Introduction

Goal

Upgrade a Bloomreach Experience Manager implementation project from version 13.0.x to 13.1.y.

Upgrade Steps

Perform Generic Minor Upgrade Steps

Follow the generic instructions for minor upgrades.

Add New HCM 'site-development' Module

If your project runs in multi site mode, please adjust your project structure to support adding development-only repository data for each site war. This step is not relevant if you are running in single-site mode.

Create a new HCM module under repository-data/site-development location.

Create the file src/main/resources/hcm-module.yaml and fill it with the following content, adjusted to your project:

site: myproject
group: myproject
project: myproject
module: 
  name: myproject-repository-data-site-development
  after: myproject-repository-data-site

Open your project's root pom.xml, locate the cargo.run Maven profile, and add the following <file> element under the <files> element:

<file>
  <file>${project.basedir}/repository-data/site-development/target/myproject-repository-data-site-development-${dollar}{project.version}.jar</file>
  <todir>${development-module-deploy-dir}</todir>
</file>

Add an additional assembly <file> element to src/main/assembly/shared-lib-development-data.xml:

<file>
  <source>repository-data/site-development/target/${artifactId}-repository-data-site-development-${dollar}{project.version}.jar</source>
  <outputDirectory>shared/lib</outputDirectory>
</file>

Move all HST development data into a the newly created module.

Add Docker Support

Bloomreach Experience Manager version 13.1.x adds Docker support to projects based on the Maven archetype.

In order to upgrade from 13.0.x to 13.1.y, the following steps should be done:

1. Generate a temporary project from the 13.1.x archetype using the same groupId, artifactId and version of the project you're upgrading. Assuming temp as the root folder of the temporary project and target as the root folder of the project that is intended to be upgraded:

• Copy the temp/conf folder from the temporary project to the target/conf folder of your target project. Override any existing files or keep them if they contain customized configuration.
• Create a db-bootstrap folder in your project's root directory.
• Copy src/main/docker directory from the temp project into the target project.

2. Open the target project's root pom.xml and perform the following actions:

• Copy paste the following maven profiles from temp/pom.xml into your's target/pom.xml:
  docker.build, docker.run, mysql, docker.mysql, postgres, docker.postgres, and docker.es.

• Add the empty property <docker.brxm.copy.dev.libs.cmd/> to the without-development-data Maven profile:

  <profile>
    <id>without-development-data</id>
    <properties>
      ......
      <!-- Skip copying development modules. Should be empty -->
      <docker.brxm.copy.dev.libs.cmd/>
    </properties>
  </profile>

Update Selection Addon Repository Dependency Scope

If your implementation project or custom plugin has a dependency on the hippo-plugin-selections-addon-repository module, you may have to update the scope of this dependency. This module now contains code that may be needed for compilation of the project or plugin. If the scope is 'runtime' it must be changed. If the dependency is part of a CMS WAR module the scope should be 'compile', otherwise it should be 'provided'.

Update @Parameter Annotations

The (undocumented) 'description' attribute of the @Parameter annotation has been deprecated in version 13.1 and will be removed in version 14.0. It is recommended that you check your project for usages of this attribute and if so, replace with hint texts in resource bundles, which are now supported for component parameters (previously only for channel parameters).

Remove Xtype Property from Catalog Component Configurations

As of version 13.1, the hst:xtype property on hst:containeritemcomponent nodes (used to configure catalog components) is no longer mandatory and in fact ignored. It is recommended to remove it from any catalog components in your implementation project.

Update Custom Field Validators

Document type validators can now be either document-scoped (default) of field-scoped. Validation messages are rendered either at the top of the editing template for document-scoped validators, or directly below the relevant field for field-scoped validators. If your implementation project contains custom field validators, it is highly recommended to configure them to be field-scoped for a better user experience.

To configure a validator as field-scoped, set the scope property to field on the frontend:plugin node for that validator. For an example, see the configuration for the out-of-the-box email validator:

/hippo:configuration/hippo:frontend/cms/cms-validators/email:
  jcr:primaryType: frontend:plugin
  plugin.class: org.hippoecm.frontend.editor.validator.plugins.RegExCmsValidator
  regex_pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,6}$
  scope: field

In addition, all field validation messages have been updated to take the form of an imperative sentence. For example, "Enter a valid email address". For a consistent user experience, it is highly recommended to update your custom validator's messages accordingly.

(Projects) Restart Campaigns that were Running before the Upgrade

Bloomreach Experience Manager version 13.1.0 introduces scheduled campaigns to Projects. In versions prior to 13.1, a project was running as a campaign if it’s state was APPROVED and it had a startDate. This start date was set by clicking Start campaign in the UI. In version 13.,1 a project is only running if it’s state is RUNNING. This means that campaigns that were started and still running before the upgrade will not be running after the upgrade and must be restarted manually.

To do this, navigate to the projects overview. Affected projects will show a red clock icon and a warning that the project was scheduled with a date in the past but is not running. For each affected project, open the project details and click on the Start campaign button.

(Projects) Upgrade Camunda Database

Bloomreach Experience Manager version 13.1 uses version 7.9.0 of the Camunda engine. If you are upgrading from 13.0 or 12.6, the Camunda database schema must be upgraded from Camunda version 7.8.0 to 7.9.0.

Please backup your Camunda database before making changes to the schema!

We provide several options to upgrade the schema:

Use Automigrate Feature

As of version Bloomreach Experience Manager version 13.1, we use the Flyway library to support automigration of the Camunda schema. After upgrading your implementation project and starting your CMS instance, Flyway will automatically migrate the schema to the required 7.9.0 version. After migration, a schema history table named flyway_schema_history will be present containing two rows. The table has more columns than shown here, but these are the most important ones.

#	version	description	type	script	success
1	7.8	<< Flyway Baseline >>	BASELINE	<< Flyway Baseline >>	1
2	7.9	mysql 7.8 to 7.9	SCRIPT	V7.9__mysql_7.8_to_7.9.sql	1

If all went well, success must be 1 in both rows after the upgrade.

If you do not want to make use of automigration, please follow one of the manual procedures for upgrading (described below) and specify the following system property when starting the CMS:

-Dbpm.autoMigrateSchema=false

Follow Procedure as Described by Camunda

Follow the three step procedure provided by Camunda:

https://docs.camunda.org/manual/7.9/update/minor/78-to-79/#procedure

Please note that the schema does not contain any version information, so you will have to keep track of this yourself!

Use Concatenated Patch and Upgrade Script

To be able to support automatic upgrade, we concatenated the 7.8 patch files and the 7.8_to_7.9 upgrade file into one file. So instead of applying the patches one by one and finally the upgrade script, you can run this single script. You can find the scripts in the hippo-addon-wpm-camunda-engine jar:

db/migration/${db_vendor}/V7.9__${db_vendor}_7.8_to_7.9.sql

Select the file for your database and run the script manually to upgrade the schema.

Please note that the schema does not contain any version information, so you will have to keep track of this yourself!