Add the Essentials Setup Application to your Project

Warning

When adding the Essentials setup application to an existing Bloomreach Experience Manager project, you should be aware of the above caveat. We recommend you use your VCS to detect and revert undesired changes by Essentials to your project.

Please use Essential's feedback mechanism to tell us about your experiences using it with an existing Bloomreach Experience Manager project. This may lead to better support of this scenario in the future.

Overview

The "installation" process works roughly like this: Create a new Bloomreach Experience Manager project from the archetype, move the Essentials setup application into your existing Bloomreach Experience Manager project, hook it into your build and deploy process and initialize it.

Upon completion of the process, you should be able to access the setup dashboard locally, browse the Library and access the pre-installed Tools.

Step 1: Create a new, empty Bloomreach Experience Manager project

The Get Started tutorial specifies how to create a new Bloomreach Experience Manager project from the (most recent) Bloomreach Experience Manager project archetype. Execute the mvn archetype:generate command in a separate directory to temporarily create a new, empty Bloomreach Experience Manager project. When prompted for the project parameters, make sure they are as close to the parameters of your existing Bloomreach Experience Manager project as possible.

Step 2: Match your project settings

In the generated, empty Bloomreach Experience Manager project, examine the root POM (pom.xml). Compare the parent version with that of your existing Bloomreach Experience Manager project. If the parent version of your existing Bloomreach Experience Manager project is lower than the parent version of the empty project, update the parent version of your existing project.

Step 3: Copy the Essentials module

The generated Bloomreach Experience Manager project contains an essentials module/directory, which represents the Essentials setup application. Copy it into the root directory of your existing Bloomreach Experience Manager project, keeping the name essentials. Then, check in essentials/pom.xml that the parent parameters (groupId, artifactId and version) correctly refer to the root POM of your existing Bloomreach Experience Manager project. If not, update these values.

Step 4: Link the essentials module into your project

Open the root POM (pom.xml) of your existing Bloomreach Experience Manager project. Add the essentials module as a new module in your modules section

<module>essentials</module>

and add the essentials WAR as a deployable, besides 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: Prepare Essentials usage in CMS and site

In order to make some of Essential's libraries available to the CMS and site modules, we manage a few dependencies centrally in the root POM. For this, add the property

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

(replace "ESSENTIALS_VERSION" with the version found in the same name property of the root POM of the generated Bloomreach Experience Manager project).

Step 6: Add support for Essentials to the site components module

To add support for Essentials to the components module of your existing Bloomreach Experience Manager project, add the following dependencies to your site/components/pom.xml file.

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

Step 7: Initialize the Essentials setup application

Now, open the file essentials/src/main/resources/project-settings.xml, and initialize the project settings:

• projectNamespace the main namespace prefix used in your existing project. By default, this can be determined by looking for the file repository-data/application/src/main/resources/hcm-config/namespaces/*.cnd. The asterisk ('*') represents your project Namespace.
• selectedBeansPackage the Java package that contains your HST beans, e.g. 'org.example.beans'.
• selectedComponentsPackage the Java package that contains your HST components, e.g. 'org.example.components'.
• selectedRestPackage the Java package where HST REST classes are located, e.g. 'org.example.rest'.
• cmsModule add this tag if the Maven module containing your CMS web application is named different from "cms". E.g. if your existing project uses "backend" as the name of the CMS WAR root folder, specify <cmsModule>backend</cmsModule>.
• siteModule add this tag if the Maven module containing your site web application is named different from "site". E.g. if your existing project uses "website" as the name of the site WAR root folder, specify <siteModule>website</siteModule>.
• repositoryDataModule add this tag if the Maven module containing your repository data modules is named different from "repository-data". E.g. if your existing project uses "initialization" as the name of the repository data modules root folder, specify <repositoryDataModule>initialization</repositoryDataModule>.
• applicationSubModule add this tag if the Maven sub-module containing your application repository data (to be deployed anywhere) is not named application.
• developmentSubModule add this tag if the Maven sub-module contining your development repository data (to be deployed to development environments only) is not named development.
• webfilesSubModule add this tag if the Maven sub-module containing your webfiles (inside the repository data folder) is named different from "webfiles". E.g. if your existing project uses "webresources" as the name of the webfiles root folder, specify <webfilesSubModule>webresources</webfilesSubModule>. 
• beansFolder add this tag if the folder containing your HST beans is outside of "site" project. The specified value represents the path relative to the project root folder, 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 auto-generated content bean classes for your document types. Most likely your project contains custom content bean classes that you don't want the Beanwriter to modify. However, you may still want to auto-generate bean classes for new document types. Therefore, annotate all methods in your existing content bean classes with @HippoEssentialsGenerated and set its allowModifications parameter to false.

Example:

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

For more information, see Creating Content Beans (section "Prevent the Beanwriter from Modifying Custom Content Beans").

Step 9: Clean up

You may have been using the generated, empty Bloomreach Experience Manager project throughout these steps as a reference. By now, you no longer need it and may want to delete it.

Try it out

You should now be able to use Essentials with your existing Bloomreach Experience Manager project. To build and run your project, you'd typically issue the command

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

If all is well, you can now access the setup dashboard at:

http://localhost:8080/essentials

More Disclaimers

As explained above, some parts of Essentials may not interact nicely with your existing Bloomreach Experience Manager project in case of conflicts between the existing project's structure and the structure expected by the setup application.

In particular, what might happen is the following: Using Essentials, you install new files into your project sources and you create new configurations, stored in the Hippo repository. When Essentials tries to install such a resource and finds that it already exists, it will not touch it. Like that, only a part of a set of coherent resources may be installed, leaving the project in an unpredictable state. It is, therefore, essential(!) that you operate Essentials carefully, and monitor the sanity of the changes made.