System Properties with Initial Value(s)
Introduction
Goal
Understand how the configuration management mechanisms handles system properties with initial value(s) 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 to specify initial value(s) that will be bootstrapped when such a property doesn't exist yet (single value property), or doesn't yet have newly added values (multi-valued property). Once initialized, or new system values have been added, such a property will be ignored by the configuration management mechanisms.
The rationale behind this behavior is that in production deployment scenarios, neither the brXM product, nor an implementation project (owned by its developers) should overwrite a system property's value or values 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 provided by Bloomreach Experience Manager is the hipposys:userrole property of the author authrole for the standard content domain at /hippo:configuration/hippo:domains/content/author.
This system property and its initial value is defined by the brXM repository module as follows:
/hippo:configuration/hippo:domains/content/author: jcr:primaryType: hipposys:authrole hipposys:role: author hipposys:userrole: .meta:category: system value: xm.content.author
The first time the repository is started (bootstraping the whole configuration) or anytime thereafter when the configured value has been changed and (at that time) the property doesn't exist, the property will be (re)created with the configured initial value (e.g. xm.content.author as above). Once a system property exists in the repository, it will be ignored by the configuration management mechanisms.
Any changes thereafter to the value of hipposys:userrole property in the brXM repository module or overriding change in an implemention project will have no effect on the existing property when bootstrapped. Runtime (production) changes made to that property therefore also won't be affected.
Unless the property is deleted from the repository and on a subsequent deployment the configured value is different from the previous deployment.
The above behavior for initial system property value(s) applies to both single and multi valued properties.
However, for multi valued system properties there is one extra (new in brXM v14) useful capability.
.meta:add-new-system-values
Some multi valued properties effectively represent a 'set' of unordered values, instead of an ordered list of values.
For such properties being able to add new initial values, even after the property already exists, can be very helpful and effective, if, and only if, the following behavior is intended and desired.
By adding the additional .meta:add-new-system-values: true to the definition of a multi value system property, additional values can be added (appended) to an existing property, without overwriting its current values.
An example for this is the hipposys:groups or hipposys:users property of the author authrole for the standard content domain at /hippo:configuration/hippo:domains/content/author:
/hippo:configuration/hippo:domains/content/author: jcr:primaryType: hipposys:authrole hipposys:role: author hipposys:groups: .meta:category: system .meta:add-new-system-values: true value: [] hipposys:users: .meta:category: system .meta:add-new-system-values: true value: []
As can be seen from the above default provided configuration, the brXM product itself doesn't specify initial values, but pre-configures the usage of .meta:add-new-system-values for implementation projects.
And actually almost all the default provided security domain authroles provide this likewise.
Their purpose is to make it easier for implementation projects to define their (additonal) initial system values if desired, while still protecting the current (and possibly other) values used in a production repository.
The logic applied is comparable to 'regular' initial system values, only adding/setting new system values if:
- some of the configured (bootstrap) property values are new, e.g. not configured in the previous deployment
- (only) those new values are added to an existing repository property, if it doesn't have them yet
How To Override Default Behavior
There may be use cases in which a project developer has a need to modify (replace) the value(s) 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 initial value(s) and force updating (replacing) its value(s) 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 section can be adapted to use method 1 by modifiying the relevant YAML source as follows:
/hippo:configuration/hippo:domains/content/author: hipposys:users: .meta:category: config operation: add type: string value: [sophie]
The implementation project now explicitly categorizes the hipposys:users 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:users property. In addition, any changes made to this file will now be automatically applied to all environments where it is deployed, and (force) override any possible customization of that property in production.