NHibernate Envers - Audit trail for NHibernate

To start working with Envers, all configuration needed is to call the extension method IntegrateWithEnvers() on the NH Configuration object, as described in the Chapter 1, Quickstart.

However, as Envers generates some entities and maps them to tables, it is possible to set the prefix and suffix that is added to the entity name to create an audit table for an entity, as well as set the names of the fields that are generated.

After the basic configuration it is important to choose the audit strategy that will be used to persist and retrieve audit information. There is a trade-off between the performance of persisting and the performance of querying the audit information. Currently there two audit strategies:

There are three ways setting property values. All examples below produce the same result (tells Envers to store entity data at delete).

//NHibernate Core syntax
nhConf.SetProperty("nhibernate.envers.store_data_at_delete", "true");

//Using SetEnversProperty extension method with type safe value input
nhConf.SetEnversProperty(ConfigurationKey.StoreDataAtDelete, true);

//Using ConfigurationKey directly with type safe value input
ConfigurationKey.StoreDataAtDelete.SetUserValue(nhConfiguration, true);
		

In more detail, below are the properties that you can pass to NHibernate.Cfg.Configuration. The property names are, from code, also available on ConfigurationKey class.

To set the value of any of the properties described above, simply add an entry to your NHibernate Core's Configuration object.

To change the name of the revision table and its fields (the table, in which the numbers of revisions and their timestamps are stored), you can use the [RevisionEntity] attribute. For more information, see Chapter 4, Logging data for revisions.

The name of the audit table can be set on a per-entity basis, using the AuditTableAttribute (attribute) or SetTableInfo() (fluent). It may be tedious to add this annotation to every audited entity, so if possible, it's better to use a prefix/suffix. As an alternative, you can create your own nhibernate.envers.table_name_strategy to set table names.

If you have a mapping with join tables, audit tables for them will be generated in the same way (by adding the prefix and suffix). If you wish to overwrite this behaviour, you can use the [JoinAuditTable] attribute.

If you'd like to override auditing behaviour of some fields/properties inherited from a non mapped base type or in an embedded component, you can apply the [AuditOverride] attribute on the subtype or usage site of the component.

If you want to audit a relation, where the target entity is not audited (that is the case for example with dictionary-like entities, which don't change and don't have to be audited), just annotate it with [Audited(targetAuditMode = RelationTargetAuditMode.NOT_AUDITED] (or use fluent configuration: ExcludeRelationData()). Then, when reading historic versions of your entity, the relation will always point to the "current" related entity. By default Envers throws when "current" entity does not exist in the database. Apply not-found="ignore" in your mapping to silence the exception and assign null value instead. Hereby solution causes implicit eager loading of to-one relations.

If you'd like to audit properties of a superclass of an entity, which are not explicitly audited (which don't have the AuditedAttribute on any properties or on the class), use [AuditOverride(ForClass = typeof(SomeEntity), IsAudited = true/false)].

If an audited entity should be created by a factory, annotate the entity with the [AuditFactory(typeof(SomeFactory))] attribute to specify the factory type. You can also pass an pre-configured instance into the fluent interface's UseFactory().

By default entity types that have been changed in each revision are not being tracked. This implies the necessity to query all tables storing audited data in order to retrieve changes made during specified revision. Envers provides a simple mechanism that creates REVCHANGES table which stores entity names of modified persistent objects. Single record encapsulates the revision identifier (foreign key to REVINFO table) and a string value.

Tracking of modified entity names can be enabled in three different ways:

Users, that have chosen one of the approaches listed above, can retrieve all entities modified in a specified revision by utilizing API described in Section 5.4, “Querying for entities modified in a given revision”.

Users are also allowed to implement custom mechanism of tracking modified entity types. In this case, they shall pass their own implementation of IEntityTrackingRevisionListener interface as the value of RevisionEntityAttribute annotation. IEntityTrackingRevisionListener interface exposes one method that notifies whenever audited entity instance has been added, modified or removed within current revision boundaries.

CustomEntityTrackingRevisionListener.cs
public class CustomEntityTrackingRevisionListener 
	: IEntityTrackingRevisionListener 
{
	public void EntityChanged(Type entityClass, string entityName, object entityId, 
		RevisionType revisionType, object revisionEntity) 
	{
		((CustomTrackingRevisionEntity)revisionEntity)
			.AddModifiedEntityName(entityClass.FullName);
	}
	
	public void newRevision(object revisionEntity) 
	{
	}
}

CustomTrackingRevisionEntity.cs
[RevisionEntity(typeof(CustomEntityTrackingRevisionListener))
public class CustomTrackingRevisionEntity 
{
	private int customId;
	
	[RevisionTimestamp]
	private long customTimestamp;
	
	private ISet<ModifiedEntityTypeEntity> modifiedEntityTypes 
						= new HashSet<ModifiedEntityTypeEntity>();
		 
	public void addModifiedEntityType(string entityName) 
	{
		modifiedEntityTypes.add(new ModifiedEntityTypesEntity(this, entityName));
	}
	
	public void removeModifiedEntityType(string entityName) 
	{
		modifiedEntityTypes.remove(new ModifiedEntityTypeEntity(this, entityName));
	}
		 
	...
}

ModifiedEntityNameEntity.cs
public class ModifiedEntityTypeEntity 
{
	private Integer id;
	
	private CustomTrackingRevisionEntity revision;
		 
	private string entityName;
		 
	...
}

var revEntity = AuditReader()
	.FindRevision(typeof(CustomTrackingRevisionEntity), revisionNumber);
var modifiedEntityTypes = revEntity.ModifiedEntityNames

By default the only information stored by Envers are revisions of modified entities. This approach lets user create audit queries based on historical values of entity's properties. Sometimes it is useful to store additional metadata for each revision, when you are interested also in the type of changes, not only about the resulting values. The feature described in Section 4.1, “Tracking entity names modified during revisions” makes it possible to tell which entities were modified in given revision. Feature described here takes it one step further. "Modification Flags" enable Envers to track which properties of audited entities were modified in a given revision.

Tracking entity changes at property level can be enabled by:

The trade-off coming with this functionality is an increased size of audit tables and a very little, almost negligible, performance drop during audit writes. This is due to the fact that every tracked property has to have an accompanying boolean column in the schema that stores information about the property's modifications. Of course it is Envers' job to fill these columns accordingly - no additional work by the developer is required. Because of costs mentioned, it is recommended to enable the feature selectively, when needed with use of the granular configuration means described above.

To see how "Modified Flags" can be utilized, check out the very simple query API that uses them: Section 5.3, “Querying for revisions of entity that modified given property”.

The entry point for this type of queries is:

var query = AuditReader().CreateQuery()
	.ForEntitiesAtRevision(typeof(MyEntity, revisionNumber);

You can then specify constraints, which should be met by the entities returned, by adding restrictions, which can be obtained using the AuditEntity factory class. For example, to select only entities, where the "name" property is equal to "John":

query.Add(AuditEntity.Property("name").Eq("John"));

And to select only entites that are related to a given entity:

query.Add(AuditEntity.Property("address").Eq(relatedEntityInstance));
// or
query.Add(AuditEntity.RelatedId("address").Eq(relatedEntityId));

You can limit the number of results, order them, and set aggregations and projections (except grouping) in the usual way. When your query is complete, you can obtain the results by calling the SingleResult() or ResultList() methods.

A full query, can look for example like this:

var personsAtAddress = AuditReader().CreateQuery()
	 .ForEntitiesAtRevision(typeof(Person), 12)
	 .AddOrder(AuditEntity.Property("surname").Desc())
	 .Add(AuditEntity.RelatedId("address").Eq(addressId))
	 .SetFirstResult(4)
	 .SetMaxResults(2)
	 .GetResultList();

The entry point for this type of queries is:

var query = AuditReader().CreateQuery()
	 .ForRevisionsOfEntity(typeof(MyEntity), false, true);

You can add constraints to this query in the same way as to the previous one. There are some additional possibilities:

Using these methods, you can order the query results by revision number, set projection or constraint the revision number to be greater or less than a specified value, etc. For example, the following query will select the smallest revision number, at which entity of class MyEntity with id entityId has changed, after revision number 42:

var revision = AuditReader().CreateQuery()
	 .ForRevisionsOfEntity(typeof(MyEntity), false, true)
	 .SetProjection(AuditEntity.RevisionNumber().Min())
	 .Add(AuditEntity.Id().Eq(entityId))
	 .Add(AuditEntity.RevisionNumber().Gt(42))
	 .GetSingleResult();

The second additional feature you can use in queries for revisions is the ability to maximalize/minimize a property. For example, if you want to select the revision, at which the value of the actualDate for a given entity was larger then a given value, but as small as possible:

var revision = AuditReader().CreateQuery()
	 .ForRevisionsOfEntity(typeof(MyEntity), false, true)
	 // We are only interested in the first revision
	 .AddProjection(AuditEntity.RevisionNumber().Min())
	 .Add(AuditEntity.Property("actualDate").Minimize()
		  .Add(AuditEntity.Property("actualDate").Ge(givenDate))
		  .Add(AuditEntity.Id().Eq(givenEntityId)))
	 .GetSingleResult();

The Minimize() and Maximize() methods return a criteria, to which you can add constraints, which must be met by the entities with the maximized/minimized properties. AggregatedAuditExpression#computeAggregationInInstanceContext() enables the possibility to compute aggregated expression in the context of each entity instance separately. It turns out useful when querying for latest revisions of all entities of a particular type.

You probably also noticed that there are two boolean parameters, passed when creating the query. The first one, selectEntitiesOnly, is only valid when you don't set an explicit projection. If true, the result of the query will be a list of entities (which changed at revisions satisfying the specified constraints).

If false, the result will be a list of three element arrays. The first element will be the changed entity instance. The second will be an entity containing revision data (if no custom entity is used, this will be an instance of DefaultRevisionEntity). The third will be the type of the revision (one of the values of the RevisionType enumeration: ADD, MOD, DEL).

The second parameter, selectDeletedEntities, specifies if revisions, in which the entity was deleted should be included in the results. If yes, such entities will have the revision type DEL and all fields, except the id, null.

For the two types of queries described above it's possible to use special Audit criteria called HasChanged() and HasNotChanged() that makes use of the functionality described in Section 4.2, “Tracking entity changes at property level”. They're best suited for vertical queries, however existing API doesn't restrict their usage for horizontal ones. Let's have a look at following examples:

var query = AuditReader().CreateQuery()
	.ForRevisionsOfEntity(typeof(MyEntity), false, true)
	.Add(AuditEntity.Id().Eq(id))
	.Add(AuditEntity.Property("ActualDate").HasChanged());

This query will return all revisions of MyEntity with given id, where the ActualDate property has been changed. Using this query we won't get all other revisions in which ActualDate wasn't touched. Of course nothing prevents user from combining HasChanged condition with some additional criteria - add method can be used here in a normal way.

var query = AuditReader().CreateQuery()
	.ForEntitiesAtRevision(MyEntity.class, revisionNumber)
	.Add(AuditEntity.Property("Prop1").HasChanged())
	.Add(AuditEntity.Property("Prop2").HasNotChanged());

This query will return horizontal slice for MyEntity at the time revisionNumber was generated. It will be limited to revisions that modified Prop1 but not Prop2. Note that the result set will usually also contain revisions with numbers lower than the revisionNumber, so we cannot read this query as "Give me all MyEntities changed in revisionNumber with Prop1 modified and Prop2 untouched". To get such result we have to use the ForEntitiesModifiedAtRevision query:

var query = AuditReader().CreateQuery()
	.ForEntitiesModifiedAtRevision(MyEntity.class, revisionNumber)
	.Add(AuditEntity.Property("Prop1").HasChanged())
	.Add(AuditEntity.Property("Prop2").HasNotChanged());

The basic query allows retrieving entity names and corresponding CLR classes changed in a specified revision:

ISet<Pair<string,Type>> modifiedEntityTypes = AuditReader()
	.CrossTypeRevisionChangesReader().FindEntityTypes(revisionNumber);

Other queries (accessible from NHibernate.Envers.ICrossTypeRevisionChangesReader):

Note that methods described above can be legally used only when default mechanism of tracking changed entity names is enabled (see Section 4.1, “Tracking entity names modified during revisions”).

The extension method Auditer() offers an alternative API to query Envers.

IEnumerable<long> example = session.Auditer().GetRevisions<MyEntity>(id);

Bags (the corresponding CLR type is IList<T>) with duplicate elements. The reason is that persisting, for example a bag of string-s, violates a principle of relational databases: that each table is a set of tuples. In case of bags, however (which require a join table), if there is a duplicate element, the two tuples corresponding to the elements will be the same. NHibernate allows this, however Envers (or more precisely: the database connector) will throw an exception when trying to persist two identical elements, because of a unique constraint violation.

There are at least two ways out if you need bag semantics: