Audit Addon Installation

The Audit Addon requires a separate license. Contact your account manager or sales representative to obtain access.

Dependencies and Versions

brXM v16.x


Optional Connector Dependency	Version
Elasticsearch	6.8.21
ActiveMQ	6.1.2

brXM v15.x


Optional Connector Dependency	Version
Elasticsearch	6.8.21
ActiveMQ	5.18.4

Installation

Follow these steps to install the Audit Addon.

1. Set the Addon Version

In the <properties> section of your root pom.xml, specify the Audit Addon version. Refer to the Release Notes for version compatibility.

<audit.addon.version>2.1.1</audit.addon.version>

2. Add Dependencies to Dependency Management

In the <dependencyManagement> section of your root pom.xml, add the following dependencies:

<dependency>
  <groupId>com.bloomreach.addons.audit</groupId>
  <artifactId>audit-addon-application</artifactId>
  <version>${audit.addon.version}</version>
</dependency>
<dependency>
  <groupId>com.bloomreach.addons.audit</groupId>
  <artifactId>audit-addon-frontend</artifactId>
  <version>${audit.addon.version}</version>
</dependency>
<dependency>  
  <groupId>com.bloomreach.addons.audit</groupId>  
  <artifactId>audit-addon-proxy</artifactId>  
  <version>${audit.addon.version}</version>
</dependency>
<!--Add only for enterprise projects that use the projects feature-->
<dependency>
  <groupId>com.bloomreach.addons.audit</groupId>
  <artifactId>audit-addon-enterprise-listeners</artifactId>
  <version>${audit.addon.version}</version>
</dependency>

3. Add the Maven Dependency Plugin

In the <plugins> section of your cms/pom.xml, add the Maven Dependency Plugin to copy static frontend resources:

<!-- This plugin copies auditsearch resources from audit-addon-frontend into the CMS webapp directory -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <executions>
    <execution>
      <id>unpack</id>
      <phase>compile</phase>
      <goals>
        <goal>unpack</goal>
      </goals>
      <configuration>
        <artifactItems>
          <artifactItem>
            <groupId>com.bloomreach.addons.audit</groupId>
            <artifactId>audit-addon-frontend</artifactId>
            <outputDirectory>src/main/webapp</outputDirectory>
            <includes>auditsearch/**</includes>
          </artifactItem>
        </artifactItems>
      </configuration>
    </execution>
  </executions>
</plugin>

4. Add Dependencies to CMS Dependencies

In the <dependencies> section of your cms-dependencies/pom.xml, add the following:

<dependency>
  <groupId>com.bloomreach.addons.audit</groupId>
  <artifactId>audit-addon-application</artifactId>
</dependency>
<dependency>
  <groupId>com.bloomreach.addons.audit</groupId>
  <artifactId>audit-addon-frontend</artifactId>
</dependency>
<dependency>   
  <groupId>com.bloomreach.addons.audit</groupId>   
  <artifactId>audit-addon-proxy</artifactId> 
</dependency>
<!--Add only for enterprise projects that use the projects feature-->
<dependency>
  <groupId>com.bloomreach.addons.audit</groupId>
  <artifactId>audit-addon-enterprise-listeners</artifactId>
</dependency>

Module Overview

audit-addon-application: Provides backend logic to listen for, process, and broadcast events to the configured persistence manager or connectors.
audit-addon-frontend: Supplies the custom perspective (using the forge iframe plugin) and frontend UI resources.
audit-addon-proxy: Implements a proxy that forwards frontend UI requests to the event data store through the backend. Use this when the frontend cannot directly access event storage due to mixed content, CORS, or internal network restrictions.
audit-addon-enterprise-listeners: Adds event listeners and handlers for enterprise features such as Projects. Include this only if your project uses these features.

Configuration

All required services for the Audit Addon are registered by com.bloomreach.addon.audit.module.AuditServicesDaemonModule. Configuration is located at:

/hippo:configuration/hippo:modules/audit-services-daemon

Configure a Custom Persistence Manager

To use an intermediate persistence manager, set the className property at:

/hippo:configuration/hippo:modules/audit-services-daemon/hippo:moduleconfig/eventstore

The addon provides com.bloomreach.addon.audit.eventstore.JcrAuditEventPersistenceManager as a default implementation of the AuditEventPersistenceManager interface, which stores events in JCR. You can implement and configure your own version of this interface to control event storage before forwarding to connectors.

Connector Configuration

The addon includes two sample connector implementations:

Elasticsearch: com.bloomreach.addon.audit.clients.ElasticSearchClient
ActiveMQ: com.bloomreach.addon.audit.clients.ActiveMQClient

Both implement the EventPersistenceStrategy interface. You can implement this interface to add custom connectors. Multiple connectors are supported. Register each connector as a node under:

/hippo:configuration/hippo:modules/audit-services-daemon/hippo:moduleconfig

Use the naming convention connector-* (for example, connector-redis, connector-mongo).

Sample Elasticsearch Connector Configuration

/hippo:configuration/hippo:modules/audit-services-daemon/hippo:moduleconfig/connector-elasticsearch:
  jcr:primaryType: hipposys:moduleconfig
  className: com.bloomreach.addon.audit.clients.ElasticSearchClient
  url: http://localhost:9200

String property	Default value	Description
url	http://localhost:9200	URL of the Elasticsearch instance
apiKey		Used as Authorization header: `ApiKey {apiKey}`
username		Used by UsernamePasswordCredentials
password		Used by UsernamePasswordCredentials

Sample ActiveMQ Connector Configuration

/hippo:configuration/hippo:modules/audit-services-daemon/hippo:moduleconfig/connector-activemq:
  jcr:primaryType: hipposys:moduleconfig
  brokerUrl: tcp://localhost:61616
  className: com.bloomreach.addon.audit.clients.ActiveMQClient
  queueName: auditqueue

String property	Default value	Description
brokerUrl	tcp://localhost:61616	URL of the ActiveMQ instance
queueName	auditqueue	Name of the queue
username		Used by ActiveMQSslConnectionFactory
password		Used by ActiveMQSslConnectionFactory
trustStorePath		Used by ActiveMQSslConnectionFactory
trustStorePassword		Used by ActiveMQSslConnectionFactory
keyStorePath		Used by ActiveMQSslConnectionFactory
keyStorePassword		Used by ActiveMQSslConnectionFactory

Disable Specific Event Handling

To disable handling for specific event actions, set the multi-valued disabled-events property on:

/hippo:configuration/hippo:modules/audit-services-daemon/hippo:moduleconfig

Frontend UI and Proxy Configuration

The production build static resources from audit-addon-frontend are served from the CMS application context. All event fetch requests are relative to the CMS context and use the pattern /cms/auditsearch/proxy/**.

The proxy implementation in audit-addon-proxy listens for requests to /cms/auditsearch/proxy/** and forwards them to the configured proxy URL. Set the proxy URL using the system variable:

auditaddon.proxy.url

Custom Perspective with External UI

If you want to use the custom perspective but provide your own frontend UI, set the iframe.src property on:

/hippo:configuration/hippo:frontend/cms/cms-static/auditsearch-iframe-perspective

Scheduled Tasks

The addon provides two scheduled tasks:

com.bloomreach.addon.audit.eventstore.AuditAddonScheduledTask: When using the JCR persistence manager, this nightly task retries sending events that previously failed to broadcast.
com.bloomreach.addon.audit.eventstore.AuditAddonESCleaner: When using Elasticsearch, configure this task to remove events older than the specified maxAgeDays.

User Permissions

To grant users access to the Audit Addon's custom perspective, assign them the xm.auditaddon.viewer user role. Ensure all relevant users have this role.