Audit Trail Module (XPO)

• Aug 21, 2024
• 6 minutes to read

The AuditTrailModule is implemented by the DevExpress.ExpressApp.AuditTrail.Xpo.v24.1.dll assembly. Install the DevExpress.ExpressApp.AuditTrail.Xpo NuGet package and use one of the following techniques to add the Audit Trail module:

• You can add modules to your application when you use the Solution Wizard to create a new XAF solution. Select modules in the Choose Additional Modules step.

• In .NET applications, you can call the AddAuditTrailXpo<TBuilder>(IModuleBuilder<TBuilder>, Action<AuditTrailOptions>) / AddAuditTrailXpo<TBuilder>(IModuleBuilder<TBuilder>) method in your WinForms / ASP.NET Core Blazor application builder.

• Alternatively, you can add these Modules to the ModuleBase.RequiredModuleTypes collection of the platform-specific Module.
• In .NET Framework applications, you can also use the Module Designer and Application Designer to add a module to your project.

Check that the DevExpress.Persistent.Base.v24.1.dll assembly is referenced in your application, since it contains XAF-independent services used by the Audit Trail module.

After the necessary assemblies listed above have been referenced, all persistent objects in the application will be audited. The default audit settings are described below.

• All persistent classes (inherited from the Base Persistent Classes) are audited by the Audit Trail system.
• All public simple and reference properties owned by persistent classes are audited. However, read-only properties (properties with no set accessor) are not audited.
• All public collection properties owned by persistent classes are audited.
• All object changes - object creation, deletion and modification, names of modified properties, initial and actual values of properties are fully audited. Current user name provided by the Security System is also saved.
• Audit information is logged to the application database.
• The real values of properties stored as blob data (e.g., images) are not saved. The “Blob data” string is saved instead.
• The null values are saved as the “N/A” string.

When the object is modified in the Detail View, the initial values are copied immediately when an object has been loaded. When the object is modified in Editable List View, initial values are copied in the BaseObjectSpace.ObjectChanged event. The actual values are collected and saved in a separate UnitOfWork in the BaseObjectSpace.Committed event.

The following table lists the changes that are logged by the Audit Trail module:

Change	Description
ObjectCreated	The audited object has been created.
InitialValueAssigned	An initial value has been assigned to the audited object before the first save.
ObjectChanged	The audited object’s property has been changed.
ObjectDeleted	The audited object has been deleted.
AddedToCollection	The audited object has been added to a collection.
RemovedFromCollection	The audited object has been removed from a collection.
CollectionObjectChanged	An object from the audited object has been changed.
AggregatedObjectChanged	The object aggregated by the audited object has been changed.
CustomData	Custom data has been added to the audit log.

In code, changes are represented by the AuditDataItem class. This class’ properties are logged. By default, they are saved to the database by an AuditDataStore object. This object creates an AuditDataItemPersistent persistent object and saves it to the database. To save changes represented by the AuditDataItem objects in another storage, inherit a custom class from the AuditDataStore class and override the Save method (see the Customize the Audit Trail System topic).

To analyze the audit log, you need to know what database tables represent it. With the Audit Trail module, the following tables are added to the database:

• AuditDataItemPersistent

  The table where AuditDataItemPersistent objects are stored. Each time one of the changes listed above is made, a new record is added to this table. The table’s AuditedObject field contains references to the corresponding records in the AuditObjectWeakReference table. The OldObject and NewObject fields contain references to the corresponding records in the XPWeekReference table. String representations of these fields are stored in the OldValue and NewValue fields, respectively.

  Note

  • The AuditedObject is null for deleting operation when the deferred deletion option is disabled for the audited type. Use the DeferredDeletionAttribute to enable it.
  • For collection modification entries (AddedToCollection, RemovedFromCollection, CollectionObjectChanged, AggregatedObjectChanged), a reference to the modified persistent object along with the object’s string representation are always stored into the OldObject / OldValue fields.

  • The Security System creates a default user that cannot access or change the audit data records. To allow a user to access these records, use the following permissions:

    // MySolution.Module/DatabaseUpdater/Updater
    defaultRole.AddTypePermission<AuditDataItemPersistent>(SecurityOperations.Read, SecurityPermissionState.Deny);
    defaultRole.AddObjectPermissionFromLambda<AuditDataItemPersistent>(SecurityOperations.Read, a => a.UserObject.Key == CurrentUserIdOperator.CurrentUserId().ToString(), SecurityPermissionState.Allow);
    defaultRole.AddTypePermission<AuditEFCoreWeakReference>(SecurityOperations.Read, SecurityPermissionState.Allow);
    

    ---

• XPWeakReference

  Contains data on the objects that have been changed. Object identifiers are stored as strings.

• AuditedObjectWeakReference

  Contains data on both objects that have been changed and objects that have taken part in a change. Object identifiers are stored in the GuidId or IntId field, depending on whether they are stored as Guid or integer values. Thus, the AuditedObjectWeakReference table represents a more convenient way to access object data in comparison to the XPWeakReference table.

It is possible to lose some of the object changes if these changes are performed within a session that is not audited. This can occur if you manually create a Session or UnitOfWork. To avoid such a failure, use the Application.CreateObjectSpace method when you need to create your own Session or UnitOfWork:

C#

IObjectSpace objectSpace = Application.CreateObjectSpace(typeof(MyBusinessClass));

VB.NET

Dim objectSpace As IObjectSpace = Application.CreateObjectSpace(GetType(MyBusinessClass))

Note

Do not write a statement like the following:

C#

Session session = new Session(...);

VB.NET

Dim session As Session = New Session(...)

Customize Change Logging in Non-Persistent Properties

The following property controls change logging for all non-persistent properties: DevExpress.Persistent.AuditTrail.ObjectAuditProcessor.ExcludeNonPersistentFromAudit. This property is set to true if the FrameworkSettingsCompatibilityMode property is v24_1 or higher. To enable change logging for individual non-persistent properties, apply a UseInAuditTrailAttribute and set its parameter to true.

If you want to enable change tracking for non-persistent properties globally, set the DevExpress.Persistent.AuditTrail.ObjectAuditProcessor.ExcludeNonPersistentFromAudit property to false. To disable change logging for individual non-persistent properties, apply a UseInAuditTrailAttribute and set its parameter to false.

Usage Specifics with Middle Tier Security

Important

In .NET Framework applications with WCF-based Middle Tier security (XPO), the client application requires rights to write to the AuditDataItemPersistent database table for the Audit Trail Module to work correctly. This may pose a security risk because it allows users to edit records in this table. Do not use our Audit Trail Module in this configuration unless you implement additional data protection on your database server or application side manually. We recommend that you migrate your application to .NET and use an ASP.NET Core WebAPI-based Middle Tier Security server. In this configuration, the audit is performed entirely on the server.

In .NET applications, you need to add the Audit Trail Module only to the server application:

File: MySolution.MiddleTier/Startup.cs

C#

public class Startup {
    // ...
    public void ConfigureServices(IServiceCollection services) {
        // ...
        services.AddXafMiddleTier(Configuration, builder => {
            builder.Modules
                .AddAuditTrailXpo()
                // ...
        }
        // ...
    }
    // ...
}