Update Document Templates

Backward-compatible changes

The most common use case concerning content changes between releases is a (backward-compatible) change to a document namespace. A document namespace defines a set of document templates available in Hippo CMS. A Hippo CMS project typically contains one custom project-specific document namespace.

The following changes to a document namespace are considered "backward-compatible":

• Addition of a new document template

• Addition of a non-required primitive field to an existing document template

• Addition of a non-required compound field to an existing document template

These changes are considered backward compatible because they do not immediately affect existing documents:

• A completely new document template does not affect existing documents because the template did not exist before.

• A new, non-required field (primitive or compound) added to an existing document template does not directly affect existing documents because existing documents of that type will still comply with the data structure since the new field is optional. When an existing document is opened in Hippo CMS the new field will automatically show in the editing template. Any value entered in the new field will be saved in the existing document as expected.

This means that existing documents do not necessarily need to be updated when the new release containing only backward-compatible changes (as defined above) is deployed.

All that needs to be updated is the document namespace itself. This can be done automatically on deployment, using reload-on-startup.

Automatic update using Reload-on-startup

Backward compatible changes to a document namespace can be applied to an existing repository automatically on deployment of the new released artifact:

1. Enable the Automatic Export feature in your development environment to automatically export any changes to your namespace as XML in the bootstrap module.

2. Make the changes to the namespace using the CMS UI in your development environment. 

3. In your project's bootstrap module make sure the relevant content initialization items use the reload-on-startup feature. The relevant initialization items are:

   • Your namespace's CND file.

   • For each document template that was added or modified, the corresponding exported XML file.

4. Commit the changes in the bootstrap module to your Version Control System (as usual).

5. Package the bootstrap module with your release artifact (as usual).

6. Deploy the release artifact in the applicable environment. Reload-on-startup will detect the new version of the namespace and replace the old namespace with the new one. 

Updating existing documents with default values for newly added fields

If you added a new non-required field (primitive or compound) to an existing document template and entered a default value for this new field, you might want to add this default value to existing documents using that template. Because the field is not required, this is optional.

If you added a new required field (primitive or compound) to an existing document template and entered a default value for this new field, you must add this default value to existing documents using that template. This is only supported for document templates using so-called Relaxed Node Types. Adding required fields to document templates using Strict Node Types is not supported.

Adding a new field with a non-empty default value is described in a separate use case: Updating Existing Content Items. 

Backward-incompatible changes

Any changes to a document namespace other than those listed under "Backward-compatible changes" is considered to be backward-incompatible and are not supported by Hippo.

Summary

• Document templates can be automatically updated at deployment time using the reload-on-startup feature. 
• Only backward-compatible changes are supported.