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

System Properties with Initial Value

Introduction

Goal

Understand how the configuration management mechanisms handles system properties with an initial value and how to override this default behavior.

Background

In general, repository data categorized as system data is not managed through the configuration management mechanisms. However, for properties categorized as 'system', it is possible for an implementation project to specify an initial value that will be bootstrapped when initializing a new repository only. Once initialized, such a property will be ignored by the configuration management mechanisms.

The rationale behind this behavior is that in production deployment scenarios, an implementation project (owned by its developers) should not overwrite a system property's value (owned by the Bloomreach Experience Manager application) in a running system after it has been initialized to prevent disrupting system functions relying on that property.

Example of Default Behavior

An example of a system property with an initial value defined in an implementation project is provided by the Bloomreach Experience Manager project archetype and concerns the hipposys:members property of the node /hippo:configuration/hippo:groups/editor.

The property is owned by Bloomreach Experience Manager's content repository application which defines it as a system property in its config repository data module:

    /hippo:configuration/hippo:groups/editor:
      jcr:primaryType: hipposys:group
      hipposys:members:
        .meta:category: system
        value: []

(See full YAML source at code.onehippo.org)

The repository-data-development module bundled with projects created using the archetype adds 'editor' (a user defined in the same module) as initial value to the hipposys:members property of /hippo:configuration/hippo:groups/editor:

    /hippo:configuration/hippo:groups/editor:
      hipposys:members:
        operation: add
        type: string
        value: [editor]

(See full YAML source at code.onehippo.org)

The result of this is that in development scenarios in which the repository-data-development module is included in the project distribution, the first time the project is started (or anytime it is started without an existing repository), a new repository will be initialized and the initial value of the hipposys:members property of /hippo:configuration/hippo:groups/editor will be set to '[editor]'. From that moment on, the property is ignored by the configuration management mechanisms. Any changes to the value of hipposys:members in the above YAML definition will have no effect on the existing property when bootstrapped.

How To Override Default Behavior

There may be use cases in which a project developer has a need to modify the value of a previously initialized system property when deploying in an existing environment. For example, an older environment may need to be brought in sync with newer ones.

There are three methods to override the configuration management mechanisms' default behavior for a system property with an initial value and force updating its value in existing environments:

  1. Use a .meta:category: config directive to override the category set for the property. This has the effect of resetting the value at bootstrap anytime the YAML files related to the property are changed.
  2. Use a YAML file to set the default value for new environments (per default behavior) and provide a Groovy updater script to add this value to existing environments. This has the effect of changing the value only once for each environment, unless the Groovy script is updated and run again, regardless of the values defined in the YAML file.
  3. Use a .meta:category: content directive on the property's parent node, provide a full definition of the node and all its properties under hcm-content/, and use the hcm-actions.yaml file with a reload action to apply this definition to all environments on their next bootstrap. This also has the effect of changing the value only once for each environment, unless the content YAML file is updated and a new HCM reload action is defined.

The example in the previous paragraph can be adapted to use method 1 by modifiying the relevant YAML source as follows:

    /hippo:configuration/hippo:groups/editor:
      hipposys:members:
        .meta:category: config
        operation: add
        type: string
        value: [sophie]

The implementation project now explicitly categorizes the hipposys:members property as 'config', overriding its original 'system' categorization and forcing it into the configuration management scope. On the next bootstrap in an existing environment, the value 'sophie' will be added to the hipposys:members property. In addition, any changes made to this file will now be automatically applied to all environments where it is deployed.

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?