Update CMS Configuration

Goal

Update project-specific CMS configuration in a particular server environment (e.g. production).

Stakeholders

Developer 

Prerequisites

All project-specific CMS configuration is stored and version-controlled in the project's bootstrap module. 

CMS Configuration

Hippo CMS configuration, stored under /hippo:configuration in the repository, contains settings for the CMS application and any plugins that might have been added. Normally configuration nodes under /hippo:configuration are originally initialized by the CMS application itself or the relevant plugin. These are the default settings and they are usually only updated by a new version of the Hippo CMS application or plugin.

However, an individual Hippo-based project might require modified or additional CMS configuration settings. Later releases of the project may further modify these already project-specific settings, in which case the CMS configuration in any target environment where the project is running, must be updated when such a new release is deployed. Luckily CMS configuration is normally not modified in a running environment in between deployments of two consecutive releases, so merging of changes is usually not required.

There are four common scenarios when updating a CMS configuration setting:

• Adding a new CMS configuration node
• Modifying a previously added CMS configuration node
• Modifying an original CMS configuration node
• Modifying a previously modified CMS configuration node

 

The recommended procedure for each of these scenarios is described in detail below.

 

Adding a new CMS configuration node

The most straightforward scenario is where a new node is added at a specific location in the JCR tree under /hippo:configuration. A common example is adding a new locale node under  /hippo:configuration/hippo:frontend/cms/cms-services/localeProviderService.

The procedure is as follows: 

1. Enable the Automatic Export feature in your development environment to automatically export any changes to your CMS configuration as XML in the bootstrap module.
2. Before you make any changes, verify that the node you want to add, does not exist at the same JCR path in the target environment.
3. Add the new node at the correct JCR path in the CMS configuration in your development environment. It will be automatically exported and added to the project's bootstrap module.
4. Verify the changes in your bootstrap module and commit them to your Version Control System (as usual).
5. Package the bootstrap module with your release artifact(s) (as usual).
6. Deploy the release artifact(s) in the target environment. The new node will be automatically added the first time the newly deployed release is started.

 

Modifying a previously added CMS configuration node 

Modifying an earlier added CMS configuration node is also fairly straightforward because the complete node is project-specific and can therefore simply be reloaded using the reload-on-startup feature.

The procedure is as follows: 

 

1. Enable the  Automatic Export feature in your development environment to automatically export any changes to your CMS configuration as XML in the bootstrap module.
2. Before you make any changes, verify that the node you want to modify, has not been modified in the target environment.
3. Make the required modifications to the CMS configuration node in your development environment. The changes will be automatically exported to the project's bootstrap module.
4. Mark the relevant initialization item (for the exported node) as reloadable in your bootstrap module.
5. Commit the changes in your bootstrap module to your Version Control System (as usual).
6. Package the bootstrap module with your release artifact(s) (as usual).
7. Deploy the release artifact(s) in the target environment. The affected node will be automatically reloaded the first time the newly deployed release is started.

 

Modifying an original CMS configuration node

This scenario is slightly more complex because it concerns a node which was initialized by a bootstrap module outside the scope of the project. This means that you cannot apply any modifications to the original initialize item and simply reload it.

Instead an additional initialize item must be created inside the scope of the project, which applies the required modifications to the existing node. This is possible using Delta XML and normally  Automatic Export can do most of the work for you.

The procedure is as follows:

1. Enable the  Automatic Export feature in your development environment to automatically export any changes to your CMS configuration as XML in the bootstrap module.
2. Before you make any changes, verify that the node you want to modify, has not been modified in the target environment.
3. Make the required modifications to the CMS configuration node in your development environment. The changes will be automatically exported to the project's bootstrap module.
4. Verify the changes in your bootstrap module and commit them to your Version Control System (as usual).
5. Package the bootstrap module with your release artifact(s) (as usual).
6. Deploy the release artifact(s) in the target environment. The affected node will be automatically reloaded the first time the newly deployed release is started.

 

Modifying a previously modified CMS configuration node

The most complex scenario is when a CMS configuration node that was modified by a previous release of the project must be modified again in a later release. There are now two existing initialize items that must be taken into account: the original initialize item outside the project that created the node and the second initialize item inside the project that modified the node.

What makes this scenario complex is the fact that Delta XML initialize items cannot be reliably reloaded. While Automatic Export can modify the Delta XML initialize item in the bootstrap module in the development environment, this will only work reliable when bootstrapping a repository from scratch. Applying the modified Delta XML to the existing previously modified node in the target environment will not work reliably because the precondition for the Delta XML (which is the original state of the node) is not met.

The recommended solution to this problem is to manually add a third initialize item, again using Delta XML, to specifically update the node from the state required by the previous release (as in the target environment) to the state required by the new release. To ensure the end state of the configuration node is the same regardless of bootstrapping a repository from scratch (e.g. on a new developer's machine) or updating an existing repository (e.g. in the production environment), care must be taken to use only those Delta XML operations that overwrite settings completely. Operations which add values to an existing (multi valued) property cannot be used as this could lead to duplicate values.

The correct procedure is as follows:

 

1. Enable the  Automatic Export feature in your development environment to automatically export any changes to your CMS configuration as XML in the bootstrap module.
2. Before you make any changes, verify that the node you want to modify, has not been modified in the target environment.
3. Make the required modifications to the CMS configuration node in your development environment. The changes will be automatically exported to the existing Delta XML initialize item in the project's bootstrap module.
4. Manually create an additional initialize item, which uses Delta XML to update the relevant CMS configuration node, assuming that node can be either in the state required by the previous release, or in the state by the current release. Make sure the initialize item's sequence number is higher than the one modified in step 3.
5. Verify the changes in your bootstrap module and commit them to your Version Control System (as usual).
6. Package the bootstrap module with your release artifact(s) (as usual).
7. Deploy the release artifact(s) in the target environment. The affected node will be automatically updated the first time the newly deployed release is started.

This scenario can also be used in those rare cases where CMS configuration in the target environment is deliberately different from the configuration stored in version control. For example there might be some environment-specific configuration setting such as a URL.

In extremly complex cases you might have to  write and execute a custom Updater Script. The script is best added to the "script registry" using the bootstrap, and then manually executed by an administrator after the new release has been deployed. 

 

Summary

• CMS configuration is normally initialized outside the scope of an individual project (i.e. by the CMS application or a plugin) and therefore cannot always be simply reloaded by the project's bootstrap.
• New project-specific CMS configuration nodes can simply be added by the project's bootstrap.
• Project-specific CMS configuration nodes added by a previous release can simply be updated using reload-on-startup.
• Original CMS configuration nodes can be modified by the project using Delta XML initialize items.
• Previously modified CMS configuration nodes can be further modified using carefully designed, manually written Delta XML initialize items.
• In very complex cases, an Updater Script might be necessary to update CMS configuration.