Update Document Templates

Goal

Deploy new or updated document templates in a particular server environment (e.g. production).

Stakeholders

Developer 

Prerequisites

Templates must have a Relaxed Content Node Type Definition (Relaxed CND).

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 Bloomreach Experience Manager. A Bloomreach Experience Manager 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 Bloomreach Experience Manager 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. The modified namespace will be automatically updated on deployment (make sure bootstrapping is enabled).

Automatic Update

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 repository-data/application module.

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

3. In your project's repository-data/application module make sure the relevant YAML sources and resources are present:

   • Your namespace's CND file.

   • For each document template that was added or modified, the corresponding exported YAML source.

4. Commit the changes in the repository-data/application module to your Version Control System (as usual).

5. Package the repository-data/application module with your release artifact (as usual).

6. Deploy the release artifact in the applicable environment. Make sure bootstrapping is enabled. The system 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 are automatically updated at deployment time.
• Only backward-compatible changes are supported.