Documentation Home

Standard Audit Logging

Available as of enterprise module version 3.2.2-GA

What Gets Logged

Broadleaf can provide field change, creation and delete level logging for configured entities. These changes can be the
result of admin user edits, or customer facing site changes.

Configuring The Standard Audit Feature

The feature requires several configuration tweaks to enable.

  1. Add support for new audit domain classes and backing database tables
  2. Configure admin security for the audit feature
  3. Configure which domain classes will be logged
  4. Configure property to enable the feature

Audit Domain Support

In your project's META-INF/persistence-core.xml file, you'll need to add some additional domain classes to be recognized by the ORM.

<persistence-unit name="blPU" transaction-type="RESOURCE_LOCAL">
...
    <class>com.broadleafcommerce.enterprise.audit.domain.AuditHeaderAttributeImpl</class>
    <class>com.broadleafcommerce.enterprise.audit.domain.AuditHeaderImpl</class>
    <class>com.broadleafcommerce.enterprise.audit.domain.AuditItemAttributeImpl</class>
    <class>com.broadleafcommerce.enterprise.audit.domain.AuditItemDMLImpl</class>
    <class>com.broadleafcommerce.enterprise.audit.domain.AuditItemStandardImpl</class>
    <class>com.broadleafcommerce.enterprise.audit.domain.AuditValueChunkAfterImpl</class>
    <class>com.broadleafcommerce.enterprise.audit.domain.AuditValueChunkBeforeImpl</class>
    <class>com.broadleafcommerce.enterprise.audit.domain.AuditValueChunkImpl</class>
...
</persistence-unit>

You'll also want to make sure you've included the backing tables to support these domain classes. This can be done using
the standard auto ddl approach using the blPU.hibernate.hbm2ddl.auto=create property to cause Hibernate to automatically
create the tables for you. However, this is only suggested/supported on local development environments. A preferable
approach would be to use Liquibase change logs to represent these table changes. Review Audit Schema
for an example of a Liquibase change log for this purpose.

Admin Security Configuration

To review audit logs in the admin, new permissions and roles much be inserted into the database to control access. We suggest
you also include the sql to achieve this as part of a Liquibase change process. However, you can also simply run sql to add
the appropriate security rows directly. Review Audit Security for an example that
inserts the appropriate permissions and makes an association to the out-of-the-box super admin role.

Configuring Scope of Logging

By declaring instances of AuditQualifyItem in your Spring configuration classes (or xml config), you can inform the audit
system on what domain classes it should monitor for changes and perform audit logging. You can specify as many instances
as you need to cover exactly the scope you want to define.

AuditQualifyItem allows you to define several properties

  1. Include: Whether or not matching domain classes should be explicity included or excluded
  2. Regex: a regular expression pattern that matches one or more target domain classes
  3. Order: the order in which the qualify item is tested

Items are matched in order against the regular expression and are either include or excluded, allowing for a very flexible
configuration. Here's an example that will only include audit logs for changes to CustomerImpl entities.

@Bean
AuditQualifyItem blAuditQualifyItemTemp() {
    AuditQualifyItem item = new AuditQualifyItem();
    item.setInclude(true);
    item.setRegex(".*(CustomerImpl)");
    return item;
}

Enabling the Feature

Finally, the feature must be enabled or it will remain dormant. Enabling is as simple as adding the audit.entity.enabled=true
property to common-shared.properties. Adding the property to a location shared by both the admin and site components
is important to make sure changes are recognized from either source.

Admin Usage

By default, once the admin security configuration is in place, you can find the Standard Audit feature underneath the
Site Updates menu section in the admin. Once on the initial screen, you can change the various filter params on the list
grid to drill-down to the specific changes you're interested in. Once you identify a change, click on it to see the detail.

Generally, you will be able to review value change detail in one of two formats. For simple field changes, you will be able to see
before and after detail. For CLOB field changes, you will be able to see a unified diff that highlights only the lines changed
in the large volume of text.

There are a significant number of properties logged, including user identity, ip address, time, etc... Review the properties
in the AuditHeaderImpl and AuditItemStandardImpl classes for a complete list of tracked data.

CSR Initiated Changes

Broadleaf includes a feature to allow a CSR to masquerade as a customer on the site. To properly audit log the user identity
as both the CSR and the customer, the CSR direct login feature must be enabled. See CSR Site Direct Login
for more information on this feature.