System Properties with Initial Value(s)

Overview

This page explains how configuration management handles system properties with initial values in Bloomreach Content. It also describes how to override the default behavior when necessary.

Default Behavior of System Properties

Repository data categorized as system data is generally not managed by the configuration management mechanisms. However, you can specify initial values for system properties. These values are bootstrapped when:

• The property does not exist (for single-value properties)
• The property does not yet contain newly added values (for multi-value properties)

After initialization, or after new system values are added, configuration management ignores the property. This approach prevents the product or implementation project from overwriting system property values in a running system, which could disrupt dependent system functions.

Example: System Property with Initial Value

Bloomreach Content provides initial values for some system properties. For example, the hipposys:userrole property of the author authrole in the standard content domain at /hippo:configuration/hippo:domains/content/author is defined as follows:

/hippo:configuration/hippo:domains/content/author:
  jcr:primaryType: hipposys:authrole
  hipposys:role: author
  hipposys:userrole:
    .meta:category: system
    value: xm.content.author
copy

On the first repository startup (when bootstrapping the configuration), or any time the property does not exist, the property is created with the configured initial value (for example, xm.content.author). Once the property exists, configuration management ignores it. Subsequent changes to the value in the repository module or in an implementation project do not affect the property after it has been bootstrapped. Runtime changes made to the property are also preserved.

If the property is deleted from the repository and a new deployment provides a different value, the new value is applied.

This behavior applies to both single-value and multi-value system properties. For multi-value properties, additional capabilities are available.

Adding New Values to Multi-Value System Properties

Some multi-value properties represent unordered sets of values rather than ordered lists. In these cases, you may want to add new initial values without overwriting existing ones. Starting with brXM v14, you can use the .meta:add-new-system-values: true directive to append new values to an existing property.

For example, the hipposys:groups and hipposys:users properties of the author authrole are defined as follows:

/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: []
copy

The default configuration does not specify initial values but enables .meta:add-new-system-values for use in implementation projects. Most default security domain authroles are configured this way.

This setup allows implementation projects to define additional initial system values as needed, while preserving existing values in the production repository.

The configuration management mechanism adds new system values only if:

1. The configured property values are new compared to the previous deployment.
2. Only those new values are added to the existing property if they are not already present.

Overriding the Default Behavior

In some scenarios, you may need to replace the value(s) of an initialized system property in an existing environment (for example, to synchronize older environments with newer ones).

You can override the default behavior in the following ways:

1. Change the Property Category to config
   Set .meta:category: config for the property. This causes the value to reset at bootstrap whenever the relevant YAML files change.
2. Use a Groovy Updater Script
   Define the default value in YAML for new environments and use a Groovy updater script to update existing environments. The script applies the change once per environment unless updated and run again.
3. Use Content Category and Reload Action
   Set .meta:category: content on the parent node, provide a full node definition under hcm-content/, and use an hcm-actions.yaml file with a reload action. This applies the definition to all environments on the next bootstrap and changes the value once per environment unless updated.

To use method 1 with the previous example, modify the YAML as follows:

/hippo:configuration/hippo:domains/content/author:
  hipposys:users:
    .meta:category: config
    operation: add
    type: string
    value: [sophie]
copy

This change categorizes the hipposys:users property as config, bringing it under configuration management. On the next bootstrap, the value sophie is added to the property in all environments. Any further changes to this file are applied automatically, overriding any local customizations of the property in production.