Add Relevance Experiments and Trends to a Project

Introduction

Goal

Add Relevance Experiments and Trends to a Bloomreach Experience Manager implementation project.

Background

Experiments and Trends are two optional features of the Relevance Module. This page explains how to add Experiments and Trends to a project and configure its data stores in a local Cargo-based development environment. After the steps explained below, the Content audiences application will contain two additional tabs called Trends and Goals.

Configuration

After installation, be sure that the dataflow configuration is correct: the Visits Aggregator and the Model Trainer should be running.

Installation through Essentials

The installation of Relevance Experiments and Trends is supported through Essentials. If you start developing a new project, make sure to check Make use of Enterprise features. Navigate to the Library tab in Essentials, locate the Relevance Experiments and Trends feature and click Install feature. Essentials then applies most of the steps documented for manual installation below to your project.

Rebuild and restart your project.

Manual Installation Instructions

The instructions below assume you already followed Add the Relevance Module to a Project.

Add the Elasticsearch Maven Plugin to the Cargo Run Profile

In your local Cargo-based development environment, use the Elasticsearch Maven Plugin to add an Elasticsearch instance to store visits data.

In your project's top-level pom.xml, locate the cargo.run profile. Make the following changes the the profile:

Add the following properties to the profile's <properties> element:

      <properties>
        <!-- existing properties here --> 
        <es.tcpPort>9300</es.tcpPort>
        <es.path>${project.build.directory}/storage</es.path>
        <es.skip.start>false</es.skip.start>
        <es.httpPort>9200</es.httpPort>
      </properties>

Directly after the profile's <plugins> opening element, add the following plugin configuration:

          <plugin>
            <groupId>com.github.alexcojocaru</groupId>
            <artifactId>elasticsearch-maven-plugin</artifactId>
            <version>${maven.plugin.elasticsearch.version}</version>
            <executions>
              <execution>
                <id>start-elasticsearch</id>
                <phase>validate</phase>
                <goals>
                  <goal>runforked</goal>
                </goals>
              </execution>
              <execution>
                <id>stop-elasticsearch</id>
                <phase>post-integration-test</phase>
                <goals>
                  <goal>stop</goal>
                </goals>
              </execution>
            </executions>
            <configuration>
              <clusterName>esDevCluster</clusterName>
              <httpPort>${es.httpPort}</httpPort>
              <transportPort>${es.tcpPort}</transportPort>
              <version>${maven.plugin.elasticsearch.configuration.version}</version>
              <keepExistingData>true</keepExistingData>
              <timeout>60</timeout>
              <skip>${targeting.elastic.disabled}</skip>
            </configuration>
          </plugin>

This will start up a local Elasticsearch instance when running mvn -P cargo.run. The visits data store is configured to use this local Elasticsearch instance by default.

Configure a JNDI Environment Variable for Elasticsearch Properties

In your local Cargo-based development environment, add a JNDI environment variable that contains configuration properties for connecting to Elasticsearch.

Add the following JNDI environment variable to conf/context.xml:

<Environment name="elasticsearch/targetingDS" type="java.lang.String"
             value="{'indexName':'visits', 'locations':['http://localhost:9200/']}" />

The visits data store will use these properties to instantiate a client for connecting to the Elasticsearch webapp that you added previously.

Enable Elasticsearch Support in HST Config Properties

In cms/src/main/webapp/WEB-INF/hst-config.properties, make sure that Relevance Elasticsearch support is not disabled:

targeting.elastic.disabled = false

Rebuild and Restart

Stop the application (if it was running), and rebuild and (re)start it as explained in the Getting Started Trail.

Verify that the Elasticsearch webapp is running correctly by browsing to the following URL:

http://localhost:9200/_cat/indices?v

You should see something like this:

health status index          pri rep docs.count docs.deleted store.size pri.store.size 
green  open   visits           1   0          0            0       159b           159b

Run in Docker

To add Relevance Elasticsearch support for Docker, follow the instructions below.

Add the following resource/environment configuration into context-mysql.xml or context-postgres.xml:

<Environment name="elasticsearch/targetingDS" type="java.lang.String"
 value="{'indexName':'visits', 'locations':['http://@es.host@:@es.port@/']}"/>

Add the following lines to mysql/setup-db.sh or postgres/setup-db.sh:

sed --in-place 's/@es.host@/'"$ELASTICSEARCH_HOST"'/' /usr/local/tomcat/conf/context-$profile.xml
sed --in-place 's/@es.port@/'"$ELASTICSEARCH_PORT"'/' /usr/local/tomcat/conf/context-$profile.xml

Add Docker elasticsearch profile

<profile>
  <id>docker.es</id>
  <properties>
    <docker.es.network.mode>custom</docker.es.network.mode>
    <docker.es.network.name>${project.artifactId}-network</docker.es.network.name>
    <docker.es.bind.1>${project.basedir}/target/elasticsearch-data:/usr/share/elasticsearch/data</docker.es.bind.1>

    <docker.es.wait.time>60000</docker.es.wait.time>
    <docker.es.wait.log>bound_addresses</docker.es.wait.log>

    <docker.db.dependsOn.container.1>es</docker.db.dependsOn.container.1>
    <docker.brxm.envRun.ELASTICSEARCH_HOST>${docker.container.es.net.myproject-network.ip}</docker.brxm.envRun.ELASTICSEARCH_HOST>
    <docker.brxm.envRun.ELASTICSEARCH_PORT>9200</docker.brxm.envRun.ELASTICSEARCH_PORT>

  </properties>
  <build>
    <plugins>
      <plugin>
        <groupId>io.fabric8</groupId>
        <artifactId>docker-maven-plugin</artifactId>
        <configuration>
          <images>
            <image>
              <name>docker.elastic.co/elasticsearch/elasticsearch:6.6.0</name>
              <alias>es</alias>
              <external>
                <type>properties</type>
                <prefix>docker.es</prefix>
                <mode>override</mode>
              </external>
              <run>
                <log>
                  <enabled>true</enabled>
                </log>
              </run>
            </image>
          </images>
        </configuration>
      </plugin>
    </plugins>
  </build>
</profile>