Upgrade Project Files

This page lists the changes to be made to the project files (meaning Maven poms, web descriptors, etc.) when upgrading from a 11.2 based project to 12.0. The changes are based on a comparison between the latest 11.2 based archetype and the latest 12.0 archetype. Some changes might not apply to you because of project customizations.

Changes in root pom.xml

Bump hippo-cms7-release version

For community projects

Your root pom.xml most likely contains a <parent> that is the hippo-cms7-release artifact. You need to bump this version to the latest patch version of 12.0 (see https://code.onehippo.org/cms-community/hippo-cms-release):

<parent>
  <groupId>org.onehippo.cms7</groupId>
  <artifactId>hippo-cms7-release</artifactId>
  <version>12.0.2</version>
</parent> 

For enterprise projects

Your root pom.xml most likely contains a <parent> that is the hippo-cms7-enterprise-release artifact. You need to bump this version to the latest patch version of 12.0 (see https://maven.onehippo.com/maven2-enterprise/com/onehippo/cms7/hippo-cms7-enterprise-release/):

<parent>
  <groupId>com.onehippo.cms7</groupId>
  <artifactId>hippo-cms7-enterprise-release</artifactId>
  <version>12.0.2</version>
</parent>

Remove patched artifacts

If your project contained patched artifacts in version 11, you should reconsider if you still require these patches in version 12. To keep your project as clean as possible, unnecessary patched artifacts should be removed. This holds true especially for patches that only override the artifact version, typically in the <properties> section of the project's root pom.xml.

Restructure the repository data modules

Fresh CMS 12 projects come with an adjusted default structure for the modules providing the application with repository data. While you can keep using the old (/bootstrap) structure, our documentation reflects the new one, and we therefore recommend adjusting your project to the new structure, too. On top of renaming the /bootstrap module to /repository-data, the upgrade steps from CMS 12 Beta to GA describe how to adjust the project structure for the repository-data submodules. At a high level, the project structure changes from

/bootstrap
  /configuration
  /content
  /webfiles

to

/repository-data
  /application
  /development
  /webfiles

Disallow Auto-Export service temporarily

While progressing through the upgrade steps you might want or need to verify the startup and behavior of the project using the cargo.run profile. Although the Auto-Export service is enabled by default, you should not run the project (through the cargo.run profile) with the Auto-Export service active until you completed all the necessary steps up to Migrate HST Channels. This is a requirement to prevent the HST Channels migration to execute prematurely, which will happen automatically (only once!) if, and only if, Auto-Export is enabled.

To disallow the Auto-Export service from running, you must temporarily add and set the repo.autoexport.allowed property to value false within the cargo.run profile:

<profile>
  <id>cargo.run</id>
  <properties>
    <repo.autoexport.allowed>false</repo.autoexport.allowed>
    ...

After completing the Upgrade Auto-Export step, above property must be removed in order to successfully complete the Migrate HST Channels step (which will again mention this necessary change then).  

Update Essentials

Essentials has never been designed to upgrade along with existing projects. If your project has a compelling reason to keep the Essentials web application beyond an upgrade, there is a page on the general aspects of adding Essentials to an existing project, which by and large covers the relevant aspects for an upgrade as well. At the very least, the Essentials version needs to be bumped, and you may need to tell Essentials that your project is still using the CMS 11 module structure: 

Bump the hippo-essentials version

Hippo CMS 12 requires hippo-essentials version 4.x. We recommend using the most recent release in this version range, which you can find in our Maven repository. This version is managed in the properties section:

<properties>
  <!-- other properties -->
  <essentials.version>4.0.2</essentials.version>
</properties>

Keep using the old module structure

If you choose not to change your project's structure (as described above), since Essentials interacts with the repository data submodules and expects them to be under /repository-data, /repository-data/application and /repository-data/development by default, you need to tell Essentials that they are still at the old location. You do so by putting the

<repositoryDataModule>bootstrap</repositoryDataModule>
<applicationSubModule>configuration</applicationSubModule>
<developmentSubModule>content</developmentSubModule>

tags into Essentials' project settings at /essentials/src/main/resources/project-settings.xml. If your project already used a custom location of the <bootstrapModule> before the upgrade, you should rename the tag from <bootstrapModule> to <repositoryDataModule> to get things working again.

Remove WEB-INF and web.xml from Essentials webapp (if present)

Prior to Bloomreach Experience Manager 10, the archetype added a WEB-INF folder and web.xml file to the essentials module when creating an implementation project. Since version 4.2.0 of the archetype (for Bloomreach Experience Manager 11), these are no longer added but used from the overlayed hippo-essentials-dashboard WAR instead. Projects previously upgraded from Bloomreach Experience Manager 10 to 11 may still contain this folder and file. While in 11 this did not cause any issues, in 12 it results in an empty Essentials Library.

Therefore, if present, remove the following folder and file from your project:

essentials/src/main/webapp/WEB-INF
essentials/src/main/webapp/WEB-INF/web.xml

Add selectedProjectPackage to project-setttings.xml (if not present)

Since version 4.2.0 of the archetype (for Hippo CMS 11), the project-settings.xml file contains an additional setting selectedProjectPackage. The value of selectedProjectPackage is the package name entered when creating the project using the archetype. This was initially not covered in the 10 to 11 upgrade documentation, so projects previously upgraded from 10 to 11 may not have this setting.

Therefore, if not present, add the following line to the file essentials/src/main/resources/project-settings.xml (within the <project> element), replacing org.example with the package name of your project:

<selectedProjectPackage>org.example</selectedProjectPackage>

(Optional) Enable Essentials Enterprise features

Some enterprise features available to Bloomreach Experience Manager customers can now be added to a project from the Essentials Library. This may be useful to existing projects.

To enable enterprise features in the Essentials Library, add the following line to the file essentials/src/main/resources/project-settings.xml (within the <project> element):

<enterprise>true</enterprise>

Update Relevance

The Elasticsearch webapp in the local Cargo-based development environment is no longer supported. If you use this webapp (hippo-addon-targeting-demo-support-elasticsearch) you can use the Elasticsearch Maven Plugin instead. 

Remove the dependency on the hippo-addon-targeting-demo-support-elasticsearch war and the deployable section in the cargo plugin for this webapp. Then follow Add the Elasticsearch Maven Plugin to the Cargo Run Profile. This will use the plugin to start and stop Elasticsearch together with Tomcat.