This article covers a Bloomreach Experience Manager version 12. There's an updated version available that covers our most recent release.

31-10-2018

Using the Configuration Verifier

Adding the Configuration Verifier to a project

The following step typically only has to be done once per project.

Bloomreach Experience Manager projects are expected to use the com.onehippo.cms7:hippo-cms7-enterprise-release parent pom, and as of version 12.0.2, the parent pom provides a custom Maven profile add-configuration-verifier, which can be executed to generate a custom Maven pom.xml, by default named configuration-verifier-pom.xml, and its accompanying configuration file configuration-verifier-config.yaml to the project.

Execute the following command from the project root folder:

mvn -N -P add-configuration-verifier

Make sure to provide the -N (--non-recursive) parameter otherwise the configuration verifier pom and config files also will be added to your sub modules!

Optionally, a runtime parameter -DverifierName may be specified to customize the (prefix) name of the files generated, e.g. executing:

mvn -N -P add-configuration-verifier -DverifierName=my-verifier

will generate the files my-verifier-pom.xml and my-verifier-config.yaml instead.

The files are generated using a custom (partial) maven archetype, which only works if neither of these files exist yet. Either remove (or rename) the existing files before invoking the above command again, or specify a custom (prefix) verifier name with the -DverifierName parameter instead.

The generated configuration-verifier-pom.xml will use the current Maven pom.xml as parent pom, with the same Maven coordinates (including its version), thereby inheriting all the project specific configurations including its profiles, like the cargo.run profile. This allows it to be used as a custom Maven pom.xml through which the cargo.run profile as setup for the project can be executed as expected, with some customizations of its own. 

The configuration-verifier-pom.xml copies the current project Maven coordinates including its version at the time when the files are generated. When updating the current project version, e.g. when tagging/releasing it, the coordinates of the configuration-verifier-pom.xml also need to be updated, likely manually!

Executing the Configuration Verifier

Running CV is done by executing the Maven cargo.run profile via the configuration-verifier-pom.xml instead of the standard pom.xml:

mvn -f configuration-verifier-pom.xml -P cargo.run

This will start Tomcat with only the cms.war deployed together with the hippo-enterprise-configuration-management-verifier-<version>.jar and the hippo-enterprise-repository-engine-<version>.jar. These jars and their versions are dependency managed by the com.onehippo.cms7:hippo-cms7-enterprise-release project parent pom.

If the Hippo Repository (database) to be used is already properly indexed, running CV typically only takes a few seconds, after which the process automatically terminates (unlike the normal execution of the cargo.run profile).

CV uses two additional parameters, and its processing can be further customized with the configuration-verifier-config.yaml file.

In the configuration-verifier-pom.xml the following two system parameters are pre-defined in the cargo.run profile, and passed on to CV:

  • repo.verify.configuration.configfile=${project.basedir}/configuration-verifier-config.yaml
    This (optional) parameter is used to tell CV where to find its (YAML) configuration file. 
When renaming or moving a configuration-verifier-pom.xml be aware of this parameter definition within it, and if needed to update it when also renaming or moving its -config.yaml file! 
  • repo.verify.configuration.exportpath=${project.basedir}/configuration-verifier-output
    This parameter defines the folder location where CV will generate its configuration delta output (if any).
This output folder will be deleted when CV starts executing: backup/rename the folder after execution of CV to retain the ouput across executions!

In general, we advise not to modify the upgrade-verifier-pom.xml (as a standard provided and generated file) to override these parameters, but instead redefine them if needed on the Maven command line using -Dparameter=value.

Configuring the Repository (database)

Using a development Repository database

By default, CV will verify the current project configuration against the current configured Hippo Repository (development) database.

That can be useful during development to verify configuration changes, before having them applied, since the last execution of the cargo.run profile.

Or when using the default (embedded) h2 database: a different repo.path parameter can be specified when invoking CV to use the database (storage folder) of a previous cleanly bootstrapped development version of the project, to verify the changes on bootstrap configurations only.

Using a production Repository database

To verify what configuration changes an updated or upgraded project will produce when released to production, first a copy (recent backup) of the Repository production database needs to be setup and configured locally. This effort is beyond the scope of this document, but as a best practice or guideline, you can follow the instructions for Use MySQL in a Development Environment.

When working with two different databases (local development and production) and two different repository storage folders as pointed at by the repo.path parameter, we advise to define two additional Maven profiles for the project, for example mysql-dev and mysql-prod, each configuring a different database connection and different repo.path parameter to be used.

Setup this way, cargo then can be executed for regular development with:

mvn -P cargo.run,mysql-dev

and CV can be executed against the production database with:

mvn -f configuration-verifier-pom.xml -P cargo.run,mysql-prod
A first execution of CV against a large (backup of a) production database may take considerable initialization time to (re)create its indices inside the repo.path storage folder.
Be sure to not accidentallly reuse the existing development repo.path storage folder for the production database, as that will result in erratic, inconsistent, broken behavior for the Hippo Repository! 

Configuring the Configuration Verifier

When executing CV, it uses configuration from configuration-verifier-config.yaml, which by default looks like: 

config:
  export:
    ignorepaths:
#      - /some/path/with/delta/which/can/be/ignored
#      - /another/path/with/delta/which/can/be/ignored
    filteruuidpaths:
#      - /some/path/for/which/uuid/export/should/be/ignored
#      - /another/path/for/which/uuid/export/should/be/ignored
    path-prefix-source-mapping:
#      /hst:hst/hst:sites: upgrade-delta-hst.yaml
#      /hst:hst/hst:configurations: upgrade-delta-hst.yaml
The default, commented out,  example configuration for the path-prefix-source-mapping as shown above and as generated by the initial release of the CV custom archetype (version 12.0.2) is incorrect, and will produce errors when activated!
Instead, the above examples for the path-prefix-source-mapping configuration should be replaced with:
#      /hst:hst/hst:sites: hst
#      /hst:hst/hst:configurations: hst

ignorepaths

When CV checks for possible differences between the new configuration and the existing data in the Hippo Repository, it skips a few hard-coded paths, as well as any path configured through the ignorepaths in  configuration-verifier-config.yaml.

The hard-coded paths (path prefixes) excluded by CV are:

- /jcr:system
- /hippo:log
- /content/attic
- /formdata
- /webfiles
- /hippo:configuration/hippo:initialize
- /hippo:configuration/hippo:update/hippo:queue
- /hippo:configuration/hippo:update/hippo:history
- /hippo:configuration/hippo:update/jcr:
- /hippo:configuration/hippo:temporary
- /hippo:configuration/hippo:modules/brokenlinks
- /hst:hst/hst:channels

For the initial usage of CV, the ignorepaths in configuration-verifier-config.yaml should be (reset to) empty, to get a first ‘raw’ report of detected deltas.

Then, after reviewing and resolving the deltas (see Resolving Configuration Verifier Deltas) they may either:

  • Need to be solved/fixed by changes in the project configuration (in case the difference is undesired or non-intended) so that a subsequent execution of CV will no longer report these
  • Are expected, intended or otherwise acceptable changes, so no longer need to be reported (unnecessary noise) by a subsequent execution of CV. The delta path can be added to the ignorepaths in configuration-verifier-config.yaml, typically accompanied with a comment explaining why.
Note that these ignorepaths are path prefixes, checked and matched by CV, they will also result in ignoring changes to child nodes and properties. Make sure to also (first) resolve reported deltas for child nodes and properties!

filteruuidpaths

CV always ignores a difference between a jcr:uuid specified through the hippo-cms product configuration (group: hippo-cms) and the actual value in the Hippo Repository, as well as jcr:uuid properties defined only in the Hippo Repository (those cannot be modified or removed without removing the mix:referenceable mixin defining that property from its node).

But as a specific jcr:uuid value, unless explicitly referenced elsewhere, typically does not need to be explicitly configured, it can be useful and even better to filter them out from the CV delta reporting through the filteruuidpaths configuration.

This serves the same purpose as the filteruuidpaths configuration used by AutoExport. Note that filteruuidpaths, as with AutoExport, are used as path prefixes.

So for example configuring /hst:hst as a filteruuidpath will filter out all jcr:uuid properties for all /hst:hst nodes. Which actually is the (only) default and predefined filteruuidpaths used by CV already.

path-prefix-source-mapping

When CV detects a difference between the new configuration and the existing data in the Hippo Repository, it will report for each difference a delta definition (see: Configuration Verifier Delta Format). The delta definitions are reported in YAML source files based on the delta definition path. CV uses a default mapping which groups specific paths to a specific source file postfix, producing YAML source files in the CV output folder using the following source file name pattern: config-delta-<postfix>.yaml

The default provided path prefix to source mapping used by the CV is the following:

/hippo:configuration/hippo:frontend: frontend         # file: config-delta-frontend.yaml
/hippo:configuration/hippo:modules: modules           # file: config-delta-modules.yaml
/hippo:configuration/hippo:queries: queries           # file: config-delta-queries.yaml
/hippo:configuration/hippo:documents: queries         # idem
/hippo:configuration/hippo:security: security         # file: config-delta-security.yaml
/hippo:configuration/hippo:domains: security          # idem
/hippo:configuration/hippo:groups: security           # idem
/hippo:configuration/hippo:roles: security            # idem
/hippo:configuration/hippo:users: users               # file: config-delta-users.yaml
/hippo:configuration/hippo:update: update             # file: config-delta-update.yaml
/hippo:configuration/hippo:workflows: workflow        # file: config-delta-workflow.yaml
/hippo:configuration/hippo:derivates: workflow        # idem
/hippo:configuration/hippo:translations: translations # file: config-delta-translations.yaml
/hippo:namespaces: namespaces                         # file: config-delta-namespaces.yaml
/hst:hst/hst:configurations/hst:default: hst          # file: config-delta-hst.yaml
/targeting:targeting: targeting                       # file: config-delta-targeting.yaml
/:                                                    # file: config-delta.yaml (catch-all)

Changing or refining the default mapping can be done through the path-prefix-source-mapping in configuration-verifier-config.yaml by adding new or overriding the default mappings.
 

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