Hippo Bootstrap Configuration Upgrade Verifier - Userguide

The Hippo Bootstrap Configuration Upgrade Verifier has been superseeded and replaced as of Bloomreach Experience Manager release v12 with the Bloomreach Experience Manager Configuration Verifier.

Introduction

The Hippo Bootstrap Configuration Upgrade Verifier is a tool to support projects and developers during the upgrade between major Bloomreach Experience Manager releases, and made available to Bloomreach Experience Manager customers and partners.
The Upgrade Verifier is provided as a separate downloadable web application and intended to be manually deployed side-by-side an existing Bloomreach Experience Manager installation.

Prerequisite

The Upgrade Verifier tool requires Java 7 or higher.

Download instructions

It is important to select and download the right version of the Upgrade Verifier, as each version is specific to verifying an upgrade between two specific Bloomreach Experience Manager releases.

The downloadable Upgrade Verifier war application is, therefore, versioned like this:

 <Hippo reference release>-<Hippo target release>-<verifier revision>

If your project is currently based on Bloomreach Experience Manager release 10.2.1 (the reference edition) and preparing for the upgrade to Bloomreach Experience Manager release 11.0.2 (the target edition), then download the web application:

hippo-bc-upgrade-verifier-10.2.1-11.0.2-<x>.war

with the highest available value for <x> (the verifier revision).

All the available Upgrade Verifier versions can be downloaded from the Bloomreach Experience Manager Artifact Repository (Nexus) at the following location:

    https://maven.onehippo.com/maven2-enterprise/com/onehippo/cms7/hippo-bc-upgrade-verifier/ (requires login)

The availability of an Upgrade Verifier implies a supported upgrade. For example, if an Upgrade Verifier is available to upgrade from Bloomreach Experience Manager release A to Bloomreach Experience Manager release C, the direct upgrade from A to C is supported by BloomReach and it is not necessary to first upgrade to any intermediate version (e.g. B).

Audience and Purpose

Audience

The Upgrade Verifier is a tool targeted at Bloomreach Experience Manager project developers, who are technically familiar with and responsible for the project specific repository configuration. This tool assumes that the developer has knowledge and experience with how the Bloomreach Experience Manager configuration bootstrap mechanism works, how it is setup and configured in the project sources, and reviewing the effective configuration in the repository under the /hippo:configuration and /hippo:namespaces using the Bloomreach Experience Manager Console.

Purpose

The purpose of the Upgrade Verifier is to assist the project developer in assessing the current project configuration state, and the potential impact of upgrading the project to a next major Bloomreach Experience Manager release.

Typically, a major upgrade will introduce or require some configuration changes, in many cases automatically 'triggered' during the startup of a freshly upgraded Bloomreach Experience Manager web application. The new web application will typically bundle newer versions of core Bloomreach Experience Manager and certified plugins artifacts, which each can contain their own specific bootstrap configuration definitions.

It is therefore critical to assess beforehand what these configuration changes are, and if and how they might affect the project specific customizations within the context of these configurations.

The Boostrap Configuration Upgrade Verifier enables a developer to review which changes the upgrade will introduce and if and how they might 'overlap' or conflict with the current project specific configurations. The Upgrade Verifier is therefore intended in the context of a running instance of the current project, ideally in the production environment or a clone thereof.

Note: the Upgrade Verifier will not make any changes in your environment and thus perfectly safe to be used in or attached to a production environment. If so desired, a separate and non-public cluster instance might be feasible to use as well. In addition and as an extra safe-guard, the Upgrade Verifier web application only allows access through a local or loop back Internet address, so outside users will never be capable of accessing the application. Since the Upgrade Verifier does not make any changes, we recommend to use the Upgrade Verifier to create a 'todo report' yourself about which bootstrap parts you need to look into.

Tip: Go through all conflicting and non-conflicting changes that the Upgrade Verifer highlights and from that, create for yourself a 'todo report' (tasks) which bootstrap items you have to look into / fix. It is upgrade specific which items you might have to give some extra attention. Version specific upgrades (say version 10 --> 11) might highlight some extra attention points you need to carefully check. 

Concepts and how it works

The Upgrade Verifier tool will compare a predefined subset of your current project repository configuration against the configuration of a 'vanilla' reference Bloomreach Experience Manager release your project is currently based upon. So if your project is based upon Bloomreach Experience Manager 10.2.1 (as configured through your project hippo-cms7-enterprise-release parent pom, version 10.2.1), you need to use the Upgrade Verifier tool specific to upgrading from 10.2.1, as it bundles a copy of the reference configuration for that specific version.

The Upgrade Verifier also bundles all the configuration upgrade changes between the 'vanilla' reference configuration and the target next major Bloomreach Experience Manager release, like for example Bloomreach Experience Manager 11.0.2. These changes have been (automatically) determined upfront by the BloomReach R&D team during development of the next major edition. The changes have further been annotated with extra information and documentation and, where feasible, with instructions how they must be handled (or like in many cases can be ignored).

Using the bundled reference configuration and upgrade changes, the Upgrade Verifier will do the following when deployed and executed against your project:

  1. Connect to your current project repository.

  2. Initialize a separate local (non-replicated) reference bootstrapped JCR workspace for your current project repository.

  3. Generate a JCR diff between the bundled reference Bloomreach Experience Manager configuration tree and your current project bootstrap configuration only reference workspace: this records all your project specific bootstrap configuration changes against the reference 'vanilla' Bloomreach Experience Manager.

  4. Generate a JCR diff between your project bootstrap configuration from the reference JCR workspace and the default JCR workspace: this records all your post-bootstrap configuration changes in your current project.

  5. Compare and match all your project bootstrap configuration changes against the bundled and annotated upgrade changes. Any significant overlapping change will be reported as conflicting bootstrap configuration change by the Upgrade Verifier, together with the annotated documentation and instructions provided by the BloomReach R&D team.

  6. Compare and match all your project post-bootstrap configuration changes against the bundled and annotated upgrade changes, and report any overlapping change as conflicting post-bootstrap configuration change.

    Critical note: The important distinction between bootstrap and post-bootstrap configuration changes is that post-bootstrap changes are NOT automatically safe-guarded and recorded in the project configuration sources. This means that if during the upgrade some of the overlapping upgrade changes are automatically applied, your project post-bootstrap configuration changes might get deleted or overwritten!
    For this reason, the Upgrade Verifier also checks and reports on the following:
  7. Check all the project post-bootstrap configuration changes against hippo:initialize configuration items which are marked as reload-on-startup or contentdelete during upgrade. For this purpose the Upgrade Verifier also bundles information about all the hippo:initialize items which might get activated during upgrade and which would trigger a reload-on-startup or contentdelete of specific configuration nodes.
    Any of your project post-bootstrap configuration changes in the scope of such reload-on-startup or contentdelete upgrade actions have a very high risk (almost certainty) of getting deleted!

Once the Upgrade Verifier has determined all the potentially conflicting upgrade changes, it will show these in several selectable reports. The developer can review these to assess the potential impact, and take actions to resolve significant conflicts before (or if feasible: after) the upgrade process.

Deploying the Upgrade Verifier web application

To use the Upgrade Verifier, just deploy the web application to a running (local) project, for example by dropping the downloaded war file (see above) in a running Tomcat webapps folder, or by configuring it as additional war deployable in the project cargo maven plugin section like:

     <profile>
      <id>cargo.run</id>
      <dependencies>
        <dependency>
          <groupId>com.onehippo.cms7</groupId>
          <artifactId>hippo-bc-upgrade-verifier</artifactId>
          <type>war</type>
          <version>7.8.8-7.9.7</version>
        </dependency>
      </dependencies>
      <build>
        <plugins>
          <plugin>
            <groupId>org.codehaus.cargo</groupId>
            <artifactId>cargo-maven2-plugin</artifactId>
            <configuration>
              <configuration>
                <deployables>
                  <deployable>
                    <artifactId>hippo-bc-upgrade-verifier</artifactId>
                    <groupId>com.onehippo.cms7</groupId>
                    <type>war</type>
                    <properties>
                      <context>/hippo-bc-upgrade-verifier</context>
                    </properties>
                  </deployable>
                  ...

In the above example the Upgrade Verifier war file has been configured on context path /hippo-bc-upgrade-verifier. If you deploy the war file manually you can rename the war file first to hippo-bc-upgrade-verifier.war (removing the version). After deploying the Upgrade Verifier manually or through cargo the application then normally wil be accessible at:

      http://localhost:8080/hippo-bc-upgrade-verifier/

The Upgrade Verifier uses basic authentication and should be logging in using a current Hippo repository (CMS) admin user. Logging in as a non-admin user might work, depending on current project configuration, but produce unexpected and unreliable results!  

Using the Upgrade Verifier

After logging in, the Upgrade Verifier will initially show the following overview information:

Review the initial overview information and make sure the correct and latest version of the Upgrade Verifier has been deployed for your current project.

Clicking the Verify button will then start the analysis, producing after a few seconds something like the following result overview: 

In this example four detail reports are available with the first one currently selected to display all conflicting configuration changes.

As explained in the Concepts and how it works section above,  post-bootstrap changes should be reviewed carefully, and therefore are also reported separately.

As a general guideline a project should contain only a minimal amount of post-bootstrap configuration changes which really cannot (or may not) be safe-guarded and merged back into project bootstrap configuration definitions on file system.
Before starting on the upgrade, it is strongly advised to review all the post-bootstrap configuration changes and try to merge as much as possible back into the project bootstrap configuration definitions. Or cleanup and remove possibly outdated or no longer needed configurations. 

For the selected report, the report items can be navigated through and reviewed individually, or displayed all at once, usefull for saving or printing the report results.

For each reported configuration conflict or change the summary information can be viewed:

or in detail with, if available, additional documentation and instructions how the interpreted and handle this change:

About the new JcrDiff format used

The Upgrade Verifier reports JCR changes in a new and enhanced JcrDiff XML format. Although the format in general is very straightforward and self-explanatory, a few important differences compared to the 'plain text' format used by the  Hippo Console Patch tool must be noted:

  • The primary d:path attribute representing a JCR repository path will not append a  child position index for each node path element between brackets like in the 'plain text' format JcrDiff
  • Instead, the d:path attribute will append the same-name-sibling (SNS) index of a node if (and only if) the node type allows same name siblings (there). And in that case it will always do so, even for default index 1, to clearly indicate the fact the specific node (path element) concerns an SNS node. Like in for example:
          d:path="/hippo:configuration/hippo:frontend/cms[1]/cms-browser[1]/navigator" 
    the cms[1] and cms-browser[1] nodes both are SNS nodes, meaning it is (technically) possible and allowed to have another cms[2] or cms-browser[2] node under the same path. In practice this isn't used much within the Hippo configuration (hippo:translation nodes being an obvious exception), but it is important to be aware of the possibility.

  • When multiple values are enumerated in a single attribute, like for the d:mixins or d:children attribute, these values will be separated by a '|' character, not a comma (the '|' character is formally illegal in JCR names, hence a safe separator, while a comma is not...).

  • A new type of change operation, d:ord-node has been added which represents a change in child nodes ordering for a specific node, if its node type indicates it allows  orderable children. In that case the names of all the current child nodes and previous child nodes are list and enumerated (see above) in the d:children and d:old-children attributes.
    Although child node order can be very significant, like for example for workflow configurations, in many cases these are not and then typically can be ignored.

Limitations

While the Upgrade Verifier very reliably will report all  potential conflicting configuration changes, sometimes or often these changes can be ignored because they represent 'false positives' or maybe concern changes which effectively won't occur during the upgrade. 

On the other hand, there might be other significant configuration changes for your project which are not, and cannot, be detected by the Upgrade Verifier.

It is therefore important to take the following known limitations into account:

  • The Upgrade Verifier can and will only detect configuration changes concerning  core and certified components and plugins of the reference and target Hippo Enterprise Edition.
  • The upgrade of non-certified components or plugins is  not covered nor supported by the Upgrade Verifier, and need to be verified separately. 
  • If certain features or components of the reference or target Hippo Enterprise Edition are not used and deployed by your project, the Upgrade Verifier might report 'false positive' conflicting changes, which in practice won't occur.
  • If your project uses different (e.g. newer) versions of core or certified components or plugins of the reference Hippo Enterprise Edition, the Upgrade Verifier might produce incorrect results. 
  • If your project already added (recommended) upstream configuration changes, the Upgrade Verifier currently still reports a conflicting configuration change, even if the change is exactly the same. A future revision of the Upgrade Verifier might be able to ignore such 'false duplicates'.
  • As mentioned above, the d:ord-node child reordering change operations in many cases can be ignored when they concern nodes for which orderable children (effectively) are not significant, or when only child nodes are added or removed. The Upgrade Verifier already 'knows' about several of such nodes which are not significantly child orderable. Future revisions will likely be able to filter out even more of these 'false positives'.

Besides the above functional limitations, as a first iteration the Upgrade Verifier is likely to have some rough edges concerning usability and possibly errors in edge-case scenarios. Any feedback and suggestions in this regard will be very much appreciated and will help to improve the Upgrade Verifier. Already reported and known limitations in this regard are:

  • When many items are reported by the Upgrade Verifier, individually navigating these becomes awkward very quickly. The suggestion for now is to use Show All in that case and browse and scroll through the accumulated report instead.
  • It would be nice if the Show Details buttons remember the previous choice when navigating between reported items. 
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?

    We rely on cookies

    to optimize our communication and to enhance your customer experience. By clicking on the Accept and Close button, you agree to the collection of cookies. You can also adjust your preferences by clicking on Manage Preferences. For more information please see our Privacy policy.

    Manage cookies
    Accept & close

    Cookies preferences

    Accept & close
    Back