Multi Delivery Web Application Mode

As of Bloomreach Experience Manager version 13, Multi Delivery Webapp Mode refers to the default structure of Bloomreach Experience Manager projects, as produced by the archetypes, which supports developing and maintaining multiple delivery web applications in the context of a single Bloomreach Experience Manager project (consisting of potentially multiple sub-projects).

Two Archetypes

As of version 13, there are two Bloomreach Experience Manager archetypes for scaffolding new Bloomreach Experience Manager sub-projects, the archetype for the parent sub-project and the archetype for a delivery webapp sub-project. A Multi Delivery Webapp Mode Bloomreach Experience Manager project consists of one parent sub-project and zero or more delivery webapp sub-projects.

Parent Sub-Project Structure

A parent sub-project is produced from the archetype org.onehippo.cms7:hippo-project-archetype. In terms of Maven modules, the structure of a base project looks like this:

/cms
/cms-dependencies
/essentials
/repository-data
  /application
  /development
  /site
  /site-development
  /webfiles
/site
  /components
  /webapp

The purpose of each module is as follows:

• cms produces the CMS/platform web application, to be shared across all delivery web applications of this Bloomreach Experience Manager project. (WAR) It depends on the cms-dependencies POM artifact.
• cms-dependencies collects all dependencies of the CMS/platform web application using POM packaging in order to facilitate the building of the CMS/platform web application in the context of delivery webapp sub-projects. It includes the dependency on the repository-data/application artifact.
• essentials produces the Essentials web application for local development. (WAR)
• repository-data logically groups all artifacts containing repository data.
• repository-data/application contains repository data definitions pertaining to the CMS/platform web application and essential to each runtime environment, including production systems. (JAR)
• repository-data/development contains repository data definitions pertaining to the CMS/platform web application used only for development and testing purposes. These definitions usually don't end up on production systems. (JAR)
• repository-data/site contains repository data definitions pertaining to the delivery web application, which primarily represent HST configuration. This JAR is packaged with the delivery web application.
• repository-data/site-development contains repository data definitions pertaining to the delivery web application used only for development and testing purposes. These definitions usually don't end up on production systems. Note: This module was added in version 13.1.0, so a project created with the 13.0.0 archetype or previous may need to be upgraded to include it. (JAR)
• repository-data/webfiles contains the webfiles pertaining to the delivery web application. This JAR, too, is packaged with the delivery web application.
• site/components contains all delivery webapp-specific code (HST components, beans etc.), as well as the delivery web application's external dependencies (on HST and 3rd party libraries). This JAR is separate from the delivery web application module, such that the webfiles module can depend on it to trigger IDE auto-completion support without introducing a circular dependency.
• site/webapp produces the delivery web application (WAR). It depends on the site/components, repository-data/webfiles and repository-data/site artifacts.

Delivery Webapp Sub-Project Structure

A delivery webapp sub-project is produced from the archetype org.onehippo.cms7:hippo-site-project-archetype. When producing such a project, you have to link it to its parent sub-project by specifying appropriate values for the following parameters:

• parentGroupId the Maven group ID of the parent sub-project

• parentArtifactId the Maven artifact ID of the parent sub-project

• parentVersion the version of the parent sub-project

In terms of Maven modules, the structure of a delivery webapp sub-project is the same as the structure of the parent sub-project (see above), however, certain modules have a conceptually different purpose:

• cms (re-)produces the parent's CMS/platform web application, potentially augmented with extra extensions (coded inside this module), dependencies (specified in the cms-dependencies module) or repository data (defined in the repository-data/application and repository-data/development modules) pertaining to CMS/platform features being developed in the context of this delivery web application. Such extras are meant for the feature development phase only. When the development of a CMS/platform feature has completed, its extras must be pushed upstream, into the parent sub-project, such that they are available to be pushed into production. After that push, these extras are no longer needed in the delivery webapp sub-project, and they must be cleaned up. In a stable delivery webapp sub-project, the cms, cms-dependencies and repository-data/application modules should be empty.
• cms-dependencies depends on the parent sub-project's cms-dependencies artifact, as well as the delivery webapp sub-project's repository-data/application artifact, and includes any temporary dependencies needed for adding CMS/platform features, to be pushed into the parent when development of a feature is done.
• repository-data/application contains temporary repository data definitions for CMS/platform features under development. When that development has completed, the corresponding definitions need to be pushed upstream, into the parent sub-project's repository-data/application module.
• repository-data/development and repository-data/site-development contain repository data definitions for the development and testing of features. If these definitions are only interesting to the local delivery webapp sub-project, they may stay in those modules forever. If they are interesting to all sub-projects of this Bloomreach Experience Manager project, they would typically be pushed to the parent sub-project upon completion of the development of the feature, and be cleaned up in the delivery webapp sub-project.

The other Maven modules of a delivery webapp sub-project serve the same purpose as described for the parent sub-project (above).

Delivery Webapp-Specific Repository Data

Multi Webapp Mode packages delivery webapp-specific repository data definitions with the delivery web application. Specifically, the delivery web application specifies dependencies on the JAR artifacts containing the delivery webapp's HST configuration (repository-data/site) and the delivery webapp's web files (repository-data/webfiles), such that these artifacts get packaged inside the delivery webapp WAR. In order for these definitions to be bootstrapped into the repository, Bloomreach Experience Manager's Configuration Management mechanism has been extended to discover the deployment of a delivery web application and process the packaged repository data definitions. A new file, hcm-site.yaml controls this mechanism, it is described below.

Multiple HST Root Nodes

In order to keep the HST configuration of a delivery web application separate from the HST configuration of all other delivery web applications, each delivery web application requests its HST configuration to be bootstrapped onto a dedicated repository root node. The delivery web application must declare which root node to use in the file src/main/webapp/META-INF/hcm-site.yaml. By default, the content of this file in a delivery webapp sub-project is:

name: mysiteproject
hstRoot: /hst:mysiteproject

The hstRoot property specifies that the HST configuration of this delivery web application is rooted at node /hst:mysiteproject.

The Configuration Management mechanism scans for the hcm-site.yaml file in a delivery web application, and, when detected, bootstraps the repository data definitions found in that delivery web application into the repository.

Your delivery web application's repository data definition YAML files do not need to specify the root node name for HST configuration exactly like specified in hcm-site.yaml. As an alternative, if the YAML files use the name /hst:hst (as in the example below), /hst:hst will be replaced by the value specified in hcm-site.yaml (i.e. /hst:mysiteproject) during bootstrapping. This mechanism allows for easier sharing or moving of HST configuration YAML files.

definitions:
  config:
    /hst:hst/hst:hosts/prod:
      jcr:primaryType: hst:virtualhostgroup
      # SNIP

Even though the definition uses /hst:hst, the prod virtual host group node will be bootstrapped below /hst:mysiteproject.

Your delivery web application must declare a dependency on org.onehippo.cms7.hst.toolkit-resources.addon:hst-addon-hcm-site, which uses this mechanism to ensure that the basic structure of the HST configuration is bootstrapped below the designated root node.

Multiple Webfile Bundles

In order to keep the web files of each delivery web application separate, each delivery web application must define its own web file bundle. The name of the web file bundle is determined through the corresponding definition in the web files artifact, typically src/main/resources/hcm-config/main.yaml:

definitions:
  webfilebundle: mysiteproject