Add the Essentials Setup Application to Your Project

Warning

The Essentials setup application is designed to simplify and accelerate the initial setup of new Bloomreach Content projects. It establishes a specific project structure, and Essentials plugins depend on this structure. Essentials does not guarantee compatibility with all existing Bloomreach Content projects. If your project structure differs from what Essentials expects, you may encounter conflicts.

If you add the Essentials setup application to an existing project, review and track all changes. Use your version control system (VCS) to identify and revert any unwanted modifications made by Essentials.

To help improve support for existing projects, provide feedback through the Essentials feedback mechanism.

Overview

To add the Essentials setup application to your project:

  1. Create a new Bloomreach Content project from the archetype.
  2. Copy the Essentials setup application into your existing project.
  3. Integrate Essentials into your build and deployment process.
  4. Initialize the setup application.

After completing these steps, you can access the setup dashboard locally, browse the Library, and use the pre-installed Tools.

Step 1: Create a New, Empty Bloomreach Content Project

Follow the Get Started tutorial to generate a new Bloomreach Content project using the latest archetype. Run the mvn archetype:generate command in a separate directory. When prompted, use project parameters that closely match those of your existing project.

Step 2: Align Project Settings

In the newly generated project, review the root POM (pom.xml). Compare the parent version with your existing project's parent version. If your existing project uses an older parent version, update it to match the new project's parent version.

Info: Regularly update your project's parent version and perform regression testing after each update. If your project's minor parent version is lower than the generated project's, either upgrade your project or consult the Essentials release notes for a compatible version.

Step 3: Copy the Essentials Module

Locate the essentials module in the generated project. Copy this directory into the root of your existing project, retaining the name essentials. In essentials/pom.xml, ensure the parent parameters (groupId, artifactId, and version) reference your existing project's root POM. Update these values if necessary.

Step 4: Add the Essentials Module to Your Project

Edit your existing project's root POM (pom.xml). Add the essentials module to the <modules> section:

<module>essentials</module>

Add the Essentials WAR as a deployable alongside the site and CMS WARs:

<deployable>
  <location>${project.basedir}/essentials/target/essentials.war</location>
  <type>war</type>
  <properties>
    <context>/essentials</context>
  </properties>
</deployable>

Step 5: Configure Essentials Dependencies

To make Essentials libraries available to the CMS and site modules, manage dependencies centrally in the root POM. Add the following property:

<essentials.version>ESSENTIALS_VERSION</essentials.version>

Replace ESSENTIALS_VERSION with the value from the generated project's root POM.

Step 6: Add Essentials Support to the Site Components Module

To enable Essentials in your components module, add the following dependency to site/components/pom.xml:

<dependency>
  <groupId>org.onehippo.cms7</groupId>
  <artifactId>hippo-essentials-components-hst</artifactId>
</dependency>

Info: The components-hst dependency provides access to standard delivery tier components. You can use these components even if you do not install the Essentials setup application.

Step 7: Initialize the Essentials Setup Application

Open essentials/src/main/resources/project-settings.xml and configure the following settings:

  • projectNamespace: The main namespace prefix used in your project. Find this in repository-data/application/src/main/resources/hcm-config/namespaces/*.cnd. The asterisk (*) represents your project namespace.
  • selectedBeansPackage: The Java package for your HST beans, for example, org.example.beans.
  • selectedComponentsPackage: The Java package for your HST components, for example, org.example.components.
  • selectedRestPackage: The Java package for your HST REST classes, for example, org.example.rest.
  • cmsModule: Specify if your CMS web application module is not named cms. For example, use <cmsModule>backend</cmsModule> if your CMS WAR root folder is named backend.
  • siteModule: Specify if your site web application module is not named site. For example, use <siteModule>website</siteModule> if your site WAR root folder is named website.
  • repositoryDataModule: Specify if your repository data module is not named repository-data. For example, use <repositoryDataModule>initialization</repositoryDataModule> if your repository data root folder is named initialization.
  • applicationSubModule: Specify if your application repository data sub-module is not named application.
  • developmentSubModule: Specify if your development repository data sub-module is not named development.
  • webfilesSubModule: Specify if your webfiles sub-module is not named webfiles. For example, use <webfilesSubModule>webresources</webfilesSubModule> if your webfiles root folder is named webresources.
  • beansFolder: Specify if your HST beans folder is outside the site project. Provide the path relative to the project root, for example, <beansFolder>beans/src/main/java</beansFolder>.

Step 8: Prevent the Beanwriter from Modifying Custom Content Beans

The Essentials setup application includes the Beanwriter tool, which can generate content bean classes for your document types. To prevent the Beanwriter from modifying your custom content bean classes, annotate all methods in your existing content bean classes with @HippoEssentialsGenerated and set allowModifications to false.

Example:

@HippoEssentialsGenerated(internalName = "myproject:title", allowModifications = false)
public String getTitle() {
    // custom content bean method implementation goes here
}

For details, see Creating Content Beans, section "Prevent the Beanwriter from Modifying Custom Content Beans".

Step 9: Clean Up

After completing these steps, you no longer need the generated, empty Bloomreach Content project. You can safely delete it.

Try It Out

You can now use Essentials with your existing Bloomreach Content project. To build and run your project, use:

mvn verify && mvn -P cargo.run -Drepo.path=./storage

After startup, access the setup dashboard at:

http://localhost:8080/essentials

Additional Considerations

Essentials may not fully integrate with existing projects if there are structural conflicts. When Essentials installs new files or configurations, it does not overwrite existing resources. As a result, only part of a set of related resources may be installed, which can leave your project in an inconsistent state. Monitor all changes made by Essentials and verify your project's integrity after each operation.

Share Feedback
Page: /build/development-tools/adding-the-setup-application
Section: Build
Category *
Add the Essentials Setup Application to your Project | Bloomreach Content Documentation