Manage Content

Bloomreach Experience Manager’s configuration management mechanism makes a clear separation between configuration and content. Reusing the concept of Groups, Projects and Modules described in Manage Configuration, while configuration is contributed by putting configuration Sources and resources into the hcm-config folder, content is contributed to the module by putting content Sources and resources in the hcm-content folder.

Also, while a configuration definition allows specifying desired changes to the Configuration Model based on fine-grained meta operations (e.g. override type of property, insert child node at specific location, see the YAML format), the handling of content is more coarse-grained, and based on content definition trees, identified by a base node.

Just like with configuration Sources, the exact name and location of the file in the hcm-content folder does not matter, so you are free to group content Sources meaningfully. However, different formatting applies to content Sources: every content Source file must contain a single content definition only, and since there is only one definition (tree), the YAML format is simplified to avoid superfluous declarations. In short, the content of a content Source file looks like this:

  /path/to/base/node:
    jcr:primaryType: <basenode:type>
    <...child properties and nodes...>

Ordering content nodes

If a new content node must be inserted at a specific location, use the order-before operation to specify before which existing sibling node the new node should be created. The order-before operation can only be specified on the base node of a content Source.

 /path/to/base/node:
    jcr:primaryType: some:type
    .meta:order-before: sibling-name
    <...child properties and nodes...>

If the node /path/to/base already has a child node sibling-name when this definition is applied, the new node is inserted right before node sibling-name. If the sibling-name node does not exist, processing of this content Source fails, and the specified content definiton is not applied.

Content bootstrapping

By default, content definitions found in the hcm-content folder will be bootstrapped into the repository if

1. The Configuration Model categorizes the base node of the content definition as content,

2. No previous content load operation has happened on the content definition’s base node, and

3. The content definition base node does not already exist in the repository.

If any of the above 3 conditions is not met, the content definition will not be loaded, unless it is referenced by a content action.

While bootstrapping the full set of configuration uses an all-or-nothing approach, bootstrapping of content works definition by definition. If the bootstrapping of a particular definition fails, Bloomreach Experience Manager issues a warning log message and continues bootstrapping the next content definition with a base node which is not a child of the base node of the failed content definition. The base node path of all successfully bootstrapped content definitions is remembered to avoid bootstrapping the same content definition twice.

Content actions

On top of above described default behaviour for bootstrapping content into the repository, Bloomreach Experience Manager supports a number of content actions for manipulating repository content during bootstrapping. These actions are specified in the optional actions file, stored as hcm-actions.yaml at the same location as where hcm-module.yaml lives.

The following actions are supported:

• delete
  Delete the base node of a tree of content nodes and properties at the specified location. Do nothing if the node doesn’t exist, or if it is not considered content. When the actions list specifies a delete action, no content Source with a matching base node should be included in the Module.

• reload
  First delete the specified base node and then append a new tree from the matching content definition. If no matching content definition is found, this action is skipped.

Typically, the default behaviour handles content appropriately, and a content actions file is rarely needed.

An example content actions file looks like this:

  action-lists:
  - 1.0:
      /content/documents/my-site/new: reload
      /content/gallery/my-site/cleaned: reload
  - 1.1:
      /content/documents/my-site/new/obsolete: delete

The content actions file contains a list of actions, grouped by a version sequence number. The sequence number has Module scope, and is used to make sure that every action is only executed once. So, if above actions list is deployed to environment E where, previously, actions with sequence number 1.0 have already been executed, the bootstrapping process will only execute actions with version number greater than 1.0. Bloomreach Experience Manager uses the same version number ordering conventions supported by Maven (see the ComparableVersion documentation).

Note that once a new action supersedes a previous one (or if, for all relevant environments, an action is no longer needed), the previous action should be removed from the actions list, along with any corresponding content Source files.

For example, in the following actions list, action 2 should be removed from the actions list, and Source c.yaml can be deleted.

  action-lists:
  - 2:
    /a/b/c: reload # -> c.yaml
  - 3:
    /a/b: reload # -> b.yaml