Audit Addon Installation

Dependencies & Versions

Bloomreach Experience Manager v16.x

Bloomreach Experience Manager v15.x

Installation

In the properties section of the root pom.xml add the version. Audit Addon Versions for different Bloomreach Experience Manager versions can be found in the Release Notes.

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

In the <dependencyManagement> section of the root pom.xml, add the below 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>

In the <plugins> section of the cms pom.xml, add the below plugin.

<!--This plugin is required to copy the resources (auditsearch) from the dependency jar audit-addon-frontend as static resources below 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>

In the <dependencies> section of the cms-dependencies pom.xml, add the below dependencies

<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>

• The module audit-addon-application contains all the necessary backend logic to listen, handle and broadcast the events to the configured persistance manager and/or connectors.
• The module audit-addon-frontend contains the custom perspective (that relies on the forge iframe plugin) and the frontend UI resources.
• The module audit-addon-proxy contains a proxy implementation that sends the requests from the frontend UI to the configured event data store through the backend. This approach can be followed in scenarios where the frontend can not directly access the event storage for reasons like mixed content, CORS, storage service exposed on internal network, etc.
• The module audit-addon-enterprise-listeners contains dedicated event listeners and handlers for enterprise features like Projects.

Configuration

All the services required and involved for the functionality of the addon are registered and managed by com.bloomreach.addon.audit.module.AuditServicesDaemonModule. The relevant configuration can be found below the node at the path

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

If you intend to use an intermediate persistence manager, this service can be configured by setting the property className at

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

The addon comes with com.bloomreach.addon.audit.eventstore.JcrAuditEventPersistenceManager one sample implementation of the interface com.bloomreach.addon.audit.eventstore.AuditEventPersistenceManager that stores the events in JCR. You can provide and configure your own implementation of this interface to store events before they are sent to different connectors.

The addon also comes with two connector sample implementations. One for Elasticsearch (com.bloomreach.addon.audit.clients.ElasticSearchClient) and one for ActiveMQ (com.bloomreach.addon.audit.clients.ActiveMQClient) both classes are implementing the interface com.bloomreach.addon.audit.clients.EventPersistenceStrategy. By implementing this interface in your project, you can configure your own connectors to send the captured events to as per requirements. You can have multiple connectors configured in your project. To register a connector, you have to create a node below 

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

and follow the node naming convention connector-* so for example : connector-redis, connector-mongo, etc.

The two sample connectors mentioned above are configured at the corresponding paths

/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

and

/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

Optionally, you can disable specific event handling based on event action by configuring the mutli-valued property disabled-events on the node

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

The production build static resources of the frontend UI from the audit-addon-frontend are served from the context of the CMS application. All the calls for fetching events are relative to the CMS context and follow the patter /cms/auditsearch/proxy/**\

The proxy implementation from the audit-addon-proxy module listens for calls to /cms/auditsearch/proxy/** and will proxy the remaining matching URL to the configured proxy URL. To configure the proxy URL where your event storage instance is hosted, you must set the system variable 

auditaddon.proxy.url

If you want to use the custom perspective but don't want to use the provided frontend UI, you can embed your own application URL by configuring the property iframe.src on the node 

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

There are two scheduled tasks offered as part of the addon implementation

• com.bloomreach.addon.audit.eventstore.AuditAddonScheduledTask - when the JCR persistance manager is used, events that fail to be broadcasted are reattempted to be sent to the configured connectors via this nightly task

• com.bloomreach.addon.audit.eventstore.AuditAddonESCleaner - when Elasticsearch is used as storage this task can be configured to clean up events older than the maxAgeDays

User Permissions

In order for users to be able to see the Audit Addon's Custom Perspective, they must be given the "xm.auditaddon.viewer" user role. Ensure that the appropriate users are given this role.