Migrate Bootstrap Resources

At the heart of the upgrade to CMS 12 lays the migration from the old, XML-based bootstrap mechanism to the new, YAML based configuration management mechanism. It is essential to a successful upgrade to CMS 12 that you have familiarized yourself with the basic concepts and format of CMS 12's configuration management mechanism.

Migrate XML to YAML

Run esv2yaml

Run the esv2yaml bootstrap resource converter to convert your existing XML bootstrap resources into YAML Sources.

Create hcm-module.yaml

After the tool completes successfully, you need to manually craft the module's /src/main/resources/hcm-module.yaml file. Make sure to merge the module's group after the hippo-cms group (and any other 3rd party groups which contribute plugins to your project, like f.e. hippo-forge). An example hcm-module.yaml file for your project's main repository-data module looks like

group:
  name: my-hippo-project
  after: [hippo-cms, hippo-forge]
project: myhippoproject
module: application

If your project contains multiple modules which contribute repository data, migrate them all, and make sure that mutual module dependencies are expressed correctly. Below example specifies that module additional-config depends on configuration contributed by (and should be merged after) module application.

group:
  name: my-hippo-project
  after: [hippo-cms, hippo-forge]
project: myhippoproject
module:
  name: additional-config
  after: application

Adjust build settings

Make sure that all resource files are actually packaged in the jar during the package phase. If during the packaging only files with specific patterns are copied, make sure to include YAML files as well such as in the below example.

<build>
  <defaultGoal>package</defaultGoal>
  <resources>
    ...
    <resource>
      <filtering>false</filtering>
      <directory>${basedir}/src/main/resources</directory>
      <includes>
        ...
        <include>**/*.cnd</include>
        <include>**/*.yaml</include>
      </includes>
    </resource>
  </resources>
</build>

Clean up the Generated YAML

Automated clean-up

As part of running esv2yaml, certain additional processing of the config and content definitions, related to upgrading from CMS 11 to CMS 12, takes place automatically. In short, the following aspects of the upgrade are taken care of:

• Project-specific customization of the HTML Cleaner is migrated to CMS 12's new HTML Processor.
• The configuration of the URL Rewriter plugin is migrated to its new, more appropriate location.
• The configuration of the Eforms Enterprise Add-on is migrated to its new, more appropriate structure.

On top of above processing of the project's bootstrap resources, some manual clean-up and changes are required:

Manual Clean-up

Content root nodes

Before CMS 12, the Hippo project contained the definitions for bootstrapping the /content node and its child nodes /documents, /gallery, /assets and /attic. These nodes are now provided by the product, and their definition can (and should) be removed from the project. You will find these in a configuration YAML source, most likely in /src/main/resources/hcm-config/content.yaml of your main repository data-contributing module. When removing these definitions, make sure to preserve any project-specific settings, such as, for example, the available folder actions (hippostd:foldertype property), gallery actions (hippostd:gallerytype property) or whether the folder is defined as a hippostd:folder or hippostd:directory (jcr:primaryType property). If they differ from the default values and you intend to preserve them, add the corresponding configuration definitions to your project.

Also, the UUID of the nodes /content and /content/documents are likely to be used in references from pieces of configuration. In order to preserve these UUIDs across the upgrade, if the UUIDs in use on your production system differ from the UUIDs provided by the CMS, make sure to override the UUIDs in your config definitions with the values used in production.

For example, to preserve the gallery actions, specify

definitions:
  config:
    /content/gallery:
      hippostd:gallerytype: [<to-be-preserved-value>]

To make the documents folder a (non-orderable) directory, and to preserve the production UUID of /content/documents, specify

definitions:
  config:
    /content/document:
      jcr:primaryType:
        operation: override
        value: hippostd:directory
      jcr:uuid: <uuid-from-production>

Reports perspective

If your project uses the Enterprise Reporting Dashboard, adding the Reports perspective to the CMS, your repository will contain the configuration of facet navigation nodes to support the reports. These nodes refer to the /content/documents node by UUID. If your production system uses, for this node, a different UUID from the one provided out of the box (and in the past, you had to manually fix these facet navigation nodes on your production system), make sure that your project preserves the facet navigation node settings currently in use on production across the upgrade by adding them as config definitions to your project. For example, for the out-of-the-box reports "Created By" and "Creation Date", specify the following config definitions:

definitions:
  config:
    /hippo:reports:
      .meta:residual-child-node-category: content
      /facet-createdby:
        hippo:docbase: <uuid-from-production>
      /facet-creationdate:
        hippo:docbase: <uuid-from-production>

If your production system exposes reports that are not bootstrapped, i.e. created in production and therefore considered 'content', you may want to add the residual-child-node-category content as shown in above example.

Formdata base structure

Your CMS 11 project may have contained definitions to bootstrap the /formdata node, along with two levels of "single-character-nodes", constituting a base structure for HST to (temporarily) store form data. As of CMS 12, these nodes are provided by the product (and/or created on the fly), and the project should no longer worry about them. So, if your migrated YAML definitions contain a config definition for /formdata (and below), this definition should be removed.

Eforms content nodes

Similar to the content root nodes, if your project is using the Eforms Enterprise Add-on, it is likely to have bootstrapped the nodes /content/eforms, /content/eform/templates and /content/eforms/fieldgroups. As of CMS 12, these nodes are bootstrapped by the Add-on, and there is no need that they are still defined in the project. They should, therefore, be removed from the project's YAML sources. Any (content!) nodes below these nodes, which should be bootstrapped should be kept as separate content Sources in the project's main module for contributing repository data (/repository-data/application, or /bootstrap/configuration if you stuck to the old project structure). If they are only relevant for development environments, they should go into the module for contributing development repository data (/repository-data/development or /bootstrap/content).

Tag cloud configuration

If your project uses the tag cloud functionality of the Tagging plugin, it used to contain the definition to bootstrap the /tags node. In CMS 12, this node is provided by the product, so most of this definition can and should be removed from the project. After the migration to YAML, your project has a definition similar to this:

definitions:
  config:
    /tags:
      jcr:primaryType: hippofacnav:facetnavigation
      hippo:docbase: <UUID of /content node>
      hippofacnav:facets: ['hippostd:tags']
      hippofacnav:limit: 100

To avoid warnings from the configuration merge process, this definition should be simplified to

definitions:
  config:
    /tags:
      hippo:docbase: <UUID of /content node>

If your project used a non-standard facet navigation limit, you may also want to retain it.

Webfiles configuration

This section is only relevant if your project uses webfiles, and if, for local development, it uses the webfiles service for automatically reloading a webfile bundle in the repository if it was changed on disk.

As of CMS 12, the product no longer provides a default configuration value specifying which module(s) to watch for changes made to webfiles on disk. As such, your project must specify that value. If, for example, your webfiles reside in module /repository-data/webfiles, make sure that the following definition is included in one of your project's config sources:

definitions:
  config:
    /hippo:configuration/hippo:modules/webfiles/hippo:moduleconfig:
      watchedModules: [repository-data/webfiles]

HTML Cleaner

While all configuration changes to the default HTML cleaners will be automatically migrated to the new HTML Processor, any custom cleaners will not be migrated. If your project has added a custom HTML cleaner, please migrate it as follows:

1. open the HTML processor configuration at /hippo:configuration/hippo:modules/htmlprocessor/hippo:moduleconfig
2. add a new node of type hipposys:moduleconfig where the node name will be used to register the HTML processor with any of the formatted or richtext fields
3. copy all existing properties apart from  plugin.class and service.id because they are no longer used (see HTML cleaning for all available properties)
4. for every whitelisted element below the original whitelist node, create a childnode below the new HTML processor configuration node of type hipposys:moduleconfig where:
   • the node-name corresponds to the name of the whitelisted HTML element
   • the property attributes can be copied as is

For more information, see the documentation on HTML cleaning.

Targeting Characteristics

If your project uses the Targeting Enterprise Add-on, and you've defined custom characteristics, you probably have created 'values' for that characteristic on the production system. Since the characteristic is a piece of config, but the value is content, you should add a residual-child-node-category: content for all custom characteristics in order to avoid that the upgrade wipes out your 'values'. Taking the 'audience' characteristic as an example, the following config definition ensures that your values of the audience characteristic are left untouched by the upgrade:

definitions:
  config:
    /targeting:targeting/targeting:characteristics/audience:
      .meta:residual-child-node-category: content
      jcr:primaryType: targeting:characteristic
      targeting:collector: audience
      targeting:scorerClassName: com.onehippo.cms7.targeting.scoring.VectorScorer