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:
- 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.
- 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.
- 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.