Reload-on-startup Initialization Items - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 10. There's an updated version available that covers our most recent release.

06-09-2016

Reload-on-startup Initialization Items

Introduction

Goal

Reload a previously loaded repository initialization item.

Use Case

Normally repository initialization items are loaded only once. The "reload on startup" feature allows you to configure initialization items to be reloaded when the CMS is restarted after an upgrade. Both node type (CND) and content (XML) items can be reloaded this way (with the exception of some delta instructions, see below). The reload is triggered only when the system detects a newer version of the initialization item than was loaded previously. This feature can help you deploy a new release of your project (e.g. containing document type modifications) in an existing environment.

To enable bootstrapping for an existing repository set the system property 
-Drepo.bootstrap=true.

Configure the Initialization Item to Reload on Startup

A reloadable initialization item requires two additional properties:

  • hippo:reloadonstartup
  • hippo:version

In the bootstrap module of your project locate the file hippoecm-extension.xml and the hippo:initializeitem you want to reload.

Add the hippo:reloadonstartup property with the value true to mark it as reloadable:

<sv:property sv:name="hippo:reloadonstartup" sv:type="Boolean">
   <sv:value>true</sv:value>
</sv:property>

And add the hippo:version property to let the system know when to reload the item:

<sv:property sv:name="hippo:version" sv:type="String">
  <sv:value>2.23.02</sv:value>
</sv:property>

The hippo:version property can be any valid Maven version number. The system will try to find the version number of the initialization item that was previously loaded. If it can't find it because it wasn't specified before, or it detects a version number that is lower than the current version number, it will reload the item. If an initialization item has the hippo:reloadonstartup property but no hippo:version property it will not be reloaded.

The hippo:version property must be a valid Maven version number. Within that constraint you can use any Maven property you like to automate versioning, such as the project version, a build number or a property based on the current time and date.

Prevent Repetitive Manual Version Updating of Frequently Updated Items

To prevent frequent manual updates of the version number use Maven resource filtering. In the pom.xml file of a module containing a hippoecm-extension.xml file, add the following configuration in the <build> section.

It includes all resources, except the hippoecm-extension.xmlwithout filtering and includes the hippoecm-extension.xml with filtering. Filtering all resources would increase the build time.
<resources>
<resource>
 <directory>src/main/resources</directory>
<filtering>true</filtering>
<includes>
<include>**/hippoecm-extension.xml</include>
</includes>
</resource>
<resource>
 <directory>src/main/resources</directory>
 <excludes>
 <exclude>**/hippoecm-extension.xml</exclude>
</excludes>
 </resource>
 </resources>

The placeholders in the hippoecm-extension.xml containing a valid Maven property will be replaced:

<sv:property sv:name="hippo:version" sv:type="String">
  <sv:value>${project.version}</sv:value>
</sv:property>

Reload of an Item in Consecutive Deployments of a SNAPSHOT Version

If a snapshot version is deployed on a regular base, for example, a continuous or daily build, and the repository content is not restored at each deployment, items using the ${project.version} placeholder are not reloaded (because the version number has not been changed). To overcome this problem, replace the -SNAPSHOT part of the Maven version by a timestamp by adding the following configuration to the <build><plugins> section of your master pom.xml:

<plugin>
 <groupId>org.codehaus.groovy.maven</groupId>
 <artifactId>gmaven-plugin</artifactId>
 <version>1.0</version>
 <executions>
 <execution>
 <phase>validate</phase>
<goals>
 <goal>execute</goal>
 </goals>
 <configuration>
 <source>
 import java.text.MessageFormat
 version= "${project.version}"
 def vartimestamp = MessageFormat.format("{0,date,yyyyMMddHHmmss}", new Date())
reloadOnStartupVersion = version.replace("SNAPSHOT",vartimestamp)
 project.properties.setProperty('reloadonstartup.version', reloadOnStartupVersion)
 </source>
 </configuration>
 </execution>
</executions>
 </plugin>

In that case, the property placeholder should be ${reloadonstartup.version}.

<sv:property sv:name="hippo:version" sv:type="String">
  <sv:value>${reloadonstartup.version}</sv:value>
</sv:property>

Same-Name Siblings and Renaming the Root Node of the Content Resource

The reload on startup feature tries to first remove the node at the document element of the content resource. For instance, if the content root was / and the document element of the content resource was <node name="foo"> it tries to remove /foo first before reimporting the content. There are two cases in which this strategy will fail to give you the results you desire. First, if there are two /foo nodes, which one to remove cannot be determined and reloading will fail with an error message being logged. The second case is when you rename the document element of the content resource. The system has no way of knowing what node was the one that was bootstrapped by an earlier version and it tries to remove the new node.

Thus beware of same-name siblings and renaming the root node of the content resource!

Delta XMLs

When the content resource is a delta with a combine or overlay directive it means that this content resource is not the one responsible for the addition of the node pointed to by the document element. This in turn means that reload on startup cannot undo the changes previously done by the initialization item. Therefore the system is unable to reload such items.

Reloading of Downstream Items

Because the reload feature removes the context node and then reimports the XML, downstream items need to be reloaded as well. Downstream items are those items that bootstrap content below that context node. For instance, say we have an item that bootstraps the node /foo and another that bootstraps the node /foo/bar then the second item is downstream from the first. In this case when the item that bootstraps /foo is to be reloaded, the item that bootstraps /foo/bar must be reloaded as well. The system automatically determines which downstream items to reload.

How to Reload Document Types

A common usage of this feature is to reload changes made to document types. In this case, you should add reloadonstartup to two initialization items:

  • The initialization item that bootstraps the CND that contains the definition of all document types. It needs to be reloaded in case of a new document type.

  • The initialization item that bootstraps the definition and configuration for document editor. Editor template configuration needs to be reloaded in case of any modification in existing document type.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?