Upgrade Considerations

CMS 12 comes with a new mechanism for configuration management. This mechanism, and its concepts, play an important role during the upgrade to CMS 12. This document describes how to apply the concepts during the upgrade, and understanding it requires that you have familiarized yourself with the concepts and formats of configuration management.

Two-dimensional Layout

CMS 12 comes with a new, two-dimensional layout for defining repository data in your project. It is important to be aware of this structure, because as part of the upgrade to CMS 12, you should carefully consider which pieces of repository data of your project should go into which slot in that two-dimensional layout.

Application vs. Development

On the first dimension, we separate definitions meant to affect all environments from definitions meant to be used in development environments only. Definitions for all environments go into the repository-data/application module, while definitions for development environments go into the repository-data/development module. Typically the content of the development repository data module depends on the application repository data module, such that you can use the application module without the development module, but you cannot use the development module without the application module.

What is a development environment?

By development environment, we refer to an environment you use during the development of your project. This may be a local environment (on a laptop, for example), or it may be on some remote server that is used for continuous integration, demo-ing or testing purposes. In both cases, what makes the environment a development environment is the fact that you regularly reset the repository to a known, initial state, which typically includes a set of test configuration and content. Content created on a development environment may be used as seed content for a production deployment, but other than that, new or changed content on a development environment is a throw-away thing without value. In contrast, content on a production system (which is kind of the opposite of a development environment) is very valuable and must be dealt with very diligently.

What is application repository data?

Any definition that should show up on a production system’s repository, upon deployment of the project, should be considered application repository data. This may include seed content in order to provide CMS author and editors with a sensible starting point for creating production content. Such content will only be bootstrapped into the repository once, and - and this is important to realize when upgrading to CMS 12 - only if the root node of each content definition Source doesn’t already exist.

Example

Say that your project’s application content definitions contain a Source rooted at /content/documents/alpha and one at /content/documents/beta. Also assume that you’re upgrading from a CMS 11 repository, which already contains a node at /content/documents/alpha, but not at /content/documents/beta.

When upgrading that repository to CMS 12, node /content/documents/alpha, along with all its properties and child nodes, will remain unchanged (content is preserved). At the same time, the content Source rooted at /content/documents/beta will be bootstrapped into the repository.

What is development repository data?

In contrast to the application repository data, all config and content definitions, which are not intended to end up on a production system should be considered development repository data. Typical examples for development repository data are:

• Test users such as the archetype’s author and editor users, along with their group memberships.

• Demo or test content, such as test fixtures relied upon by automated testing, or a set of content to facilitate manual smoke/regression testing or demonstration of relevant project features.

• Demo or test configuration, such as configuration of the auto-export functionality (relevant only for local deployments with access to the project sources), or facet navigation nodes used for demo or test reports

Deploying to a production (-like) environment

When deploying a distribution of your project to a production environment (or a production-like environment such as Acceptance), you should make sure that the development repository data module is not part of the distribution.

If you are working on validating an upgraded project against a production database copy locally, using the Maven cargo plugin, you also should not include development repository data in your setup. The CMS 12 archetype provides the -Pwithout-development-data Maven profile for this purpose, which you may want to add to your project.

Deploying to a development environment

When deploying to a local development environment (your laptop), make sure that both the application repository data module and the development repository data module are deployed. In CMS 12’s archetype, the development module is included by default when deploying your project locally, but existing (upgraded) projects may define a dedicated Maven profile for this, such as -Plocal.

When deploying to a remote development environment, also make sure that both the application and the development module are included in your distribution. While the development module is most likely excluded by default when you build a distribution of your project, the CMS 12 archetype comes with the -Pdist-with-development-data Maven profile to include the development module in your distribution.

Config vs. Content

The second dimension for arranging your project’s repository data definitions is achieved by separating config and content. In order to do so, both the application and the development module may contain a hcm-config and a hcm-content folder in their /src/main/resources directory.

Note that in previous Bloomreach Experience Manager releases, config and content were only very loosely defined and typically, each had their own "bootstrap module". In Bloomreach Experience Manager 12, config and content are much more strictly defined and are now separated within each repository data module.

What is Config?

Basically, ‘config’ is any repository data which is owned (created and maintained) by a Hippo project developer, and which is driven from the project’s sources. CMS 12’s configuration management mechanism subdivides this data into namespace, webfilebundle and config definitions.

The hcm-config folder should contain all YAML Sources which define configuration data, namespaces and webfile bundles*. The config data, in turn, not only contains definitions for configuration nodes and properties, but also repository data categorization (What subtrees are content? What subtrees or properties are system?) and initial values for system data.

Any externalized resources, referred to by the config or namespace definitions, also go into the hcm-config folder. During the upgrade is a good moment to improve your repository data, for example by externalizing updater scripts, such that the Groovy code is no longer embedded in the YAML Source, but more readable and maintainable in a separate *.groovy file. The same may be beneficial for configuration strings using the JSON format.

*CMS 12 still (like CMS 11) has the limitation that a Maven module which contributes webfiles will get all directories under /src/main/resources bootstrapped into the repository’s /webfiles. For that reason, we recommend to keep your webfiles in a Maven module separate from the application and development modules.

What is Content?

In contrast to ‘config’, ‘content’ is any repository data which is owned (created and maintained) by CMS users. This includes primarily documents, image sets and assets, but also parts of the HST configuration data which can be adjusted by webmasters in the Channel Manager (and are stored in the “hst:workspace”, per configuration), or editable data provided by plugins and add-ons, such as URL rewriter rules, Relevance characteristics or reusable parts of forms.

Since this data can be created in the CMS, it is fair to ask why content even has a place in CMS 12’s configuration management mechanism. The answer is: because we need to be able to bootstrap seed, test and demo content. While test and demo content typically go into the development data module, seed content is what you’ll most likely encounter in the application data module. In cases where your seed content overlaps / conflicts with test or demo content, you could even consider introducing an extra repository data module, to contain data which is not intended to be included on development environments.

The hcm-content folder must only contain YAML content Sources, i.e. a single definition (root) per Source. Also, the definition root nodes in your hcm-content folder must match with the repository data categorization, as specified in the config data. If you root a subtree of content at a node which is not declared to be content in your configuration model, the CMS will throw an exception.

CMS 12’s configuration management mechanism has been designed to be very careful not to interfere with any repository data marked as content. It therefore remembers when a piece (subtree) of content is bootstrapped, in order not to bootstrap it again later. As such, once the seed content has been bootstrapped, its ownership is transferred from the Hippo project developer (who developed the seed content) to the CMS user (who will maintain the content, going forward). Also, during the upgrade to CMS 12, as described above, if at the location of a piece of seed content, content already exists in the repository, CMS 12 will not attempt to bootstrap that seed content, because this could mess up the existing content.

While messing up existing content is a risk for a production environment, on a development environment, there is, by definition, no existing content, and therefore, careful categorization into config and content is less important for the repository data in the development module. In order to get used to carefully working with config and content in the application module, we recommend to apply the same approach to the development module anyway. But yes, you do have more ‘freedom’ there.

Custom Categorization

Appropriate categorization of the repository data into config and content is thus essential to a proper operation (and upgrade) of your project. Hippo CMS attempts to provide a sensible categorization out of the box (i.e. by means of the esv2yaml migration tool and the auto export configuration), but your project may have specific reasons to adopt a modified categorization. If that’s the case, it is your task to customize the categorization in your application module’s config definitions appropriately. Make sure to validate the effect of these customizations before you deploy an upgrade to a production system, in order to avoid accidental loss (or mix-up) of your project’s precious content.

Upgrading to CMS 12

Awareness and understanding of above concepts are important to a successful upgrade to CMS 12. Working through the documented upgrade steps, and especially when processing the output of the Configuration Verifier, keep them in mind when determining how to arrange the repository data definitions of your project.