Upgrade 13.2 to 13.3

Introduction

Goal

Upgrade a Bloomreach Experience Manager implementation project from version 13.2.x to 13.3.y.

Upgrade Steps

Perform Generic Minor Upgrade Steps

Follow the generic instructions for minor upgrades.

Changes in 13.3 that possibly impact your implementation project

New Validation Service

A new validation service has been introduced in 13.3 that is fully compatible with both the document editor in the Content perspective and the visual editor in the Channels perspective. This validation service is meant as a replacement for the existing Wicket-based validation API, which will most likely be removed in 14.0. Default validators have been reimplemented using the new API and their configuration has been moved to the new validation service.

If your implementation project contains customizations of the default validators, they must be verified and possibly reconfigured and/or refactored when upgrading to 13.3 as they may rely on no longer existing configuration. In this case, at the very least their bootstrap configuration must be updated. However, it is recommended to refactor custom validators to implement the new org.onehippo.cms.services.validation.api.Validator interface so they are fully compatible with the visual editor. See Create a Custom Validator for details.

Simplified Required Validator

With the introduction of the new validation service in 13.3 (see above), the required validator has been refactored. Previously, validating required fields involved using combinations of different validators. This has been replaced with just one "required" validator which uses several validators internally that perform actual validation based on the type of the validated field.

If your implementation project's document types have any required validators defined, they will automatically be mapped to the new validators as follows:

• the combination of "required" and "non-empty" becomes just "required"

• the "resource-required" validator becomes "required"

• the "html" validator becomes "non-empty-html"

• for Html fields (a.k.a. "formatted text"), the "non-empty" validator becomes "non-empty-html"

However, it is recommended to proactively clean up old validator names and combinations in your document type definitions, as this will most likely be required when upgrading to 14.0 in the near future. An Updater script is provided to do this cleanup for you.

Setting Group Id(GID) and User Id(UID) of the User in the Docker Configuration

A new property named docker.brxm.container.gid has been added to the Docker configuration. The default value of this parameter is 1001. Previously, GID was not customizable and the value was identical to UID. In addition, for the development image, UID, GID, and the name of the user in the Docker container are now also customizable using docker.brxm.container.dev.uid, docker.brxm.container.dev.gid, and docker.brxm.container.dev.username properties.

On Linux OS, if you get permission errors while running the Docker container, then you may need to tweak the UID and GID values.

See the Run with Docker on local Linux OS section in the Run and Develop with Docker page for more information.  

In addition to that, a new log4j configuration file that prints logs to the console with production level configuration is defined and set as default.

In order to upgrade from 13.2.x to 13.3.y, generate a temporary project from the 13.3.x archetype. 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.
• Copy src/main/docker directory from the temp project into the target project.

Updating getProperty() method references

As getProperty() method in HippoBean is deprecated in 13.3.0, getProperty() method references should be updated to either getSingleProperty() for single fields or getMultipleProperty() for multiple fields.

For instance, a document bean like this;

public class NewsDocument extends HippoDocument {

    @HippoEssentialsGenerated(internalName = "myproject:title")
    public String getTitle() {
        return getProperty("myproject:title");
    }

    @HippoEssentialsGenerated(internalName = "myproject:labels")
    public String[] getLabels() {
        return getProperty("myproject:labels);
    }

}

Should be updated like this;

public class NewsDocument extends HippoDocument {

    @HippoEssentialsGenerated(internalName = "myproject:title")
    public String getTitle() {
        return getSingleProperty("myproject:title");
    }

    @HippoEssentialsGenerated(internalName = "myproject:labels")
    public String[] getLabels() {
        return getMultipleProperty("myproject:labels);
    }

}

Note: Multi-site projects generated with project archetype versions 13.0.1, 13.1.0, or 13.2.0

The hippo-site-project-archetype used to create separate "site projects" for multi-site mode contained a bug in the versions listed above. This resulted in a missing configuration file that prevented correct operation of the auto-export feature for site developers. If you are using multi-site mode and have a site project that was created with one of the affected versions, you will need to manually adjust your project to fix the issue.

Add a new configuration file repository-data/application/src/main/resources/hcm-config/configuration/modules/autoexport-module.yaml with contents like the following, with the bold strings replaced with the site name provided when you created the project.

definitions:
  config:
    /hippo:configuration/hippo:modules/autoexport:
      /hippo:moduleconfig:
        autoexport:modules: ['repository-data/application:/',
                             'repository-data/site:mysiteproject:/hst:mysiteproject']