Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Collapse]eXpressApp Framework
 [Expand]Fundamentals
 [Expand]Getting Started
 [Collapse]Concepts
  [Expand]Application Solution Components
  [Expand]Business Model Design
  [Expand]Application Model
  [Expand]UI Construction
  [Expand]Extend Functionality
  [Expand]Data Manipulation and Business Logic
  [Expand]Security System
  [Expand]Localization
  [Expand]System Module
  [Collapse]Extra Modules
   [Collapse]Audit Trail Module Overview
     Analyze the Audit Log
     Customize the Audit Trail System
     Server-Side Timestamping in the Audit Trail System
    Business Class Library Customization Module
    Chart Module
    Clone Object Module
   [Expand]Conditional Appearance Module Overview
   [Expand]Dashboards Module
    File Attachments Module Overview
    HTML Property Editor Module
   [Expand]Notifications Module
    KPI Module
   [Expand]Maps Module
   [Expand]Pivot Chart Module
    Pivot Grid Module
   [Expand]Reports V2 Module
   [Expand]Reports Module (Obsolete)
   [Expand]Scheduler Module
    Script Recorder Module
   [Expand]State Machine Module
   [Expand]TreeList Editors Module
   [Expand]Validation Module
    View Variants Module
   [Expand]Workflow Module
  [Expand]Debugging and Error Handling
  [Expand]Filtering
  [Expand]Application Life Cycle
 [Expand]Design-Time Features
 [Expand]Functional Testing
 [Expand]Deployment
 [Expand]Task-Based Help
 [Expand]Frequently Asked Questions
 [Expand]API Reference
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
[Expand]End-User Documentation

Customize the Audit Trail System

The Audit Trail System represented by the Audit Trail module provides a ready-to-use mechanism for logging changes made to persistent objects. 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.
Note

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 Unit of Work in the BaseObjectSpace.Committed event.

You can customize Audit Trail System at different points. This topic details various customizations.

Expanded Change Object Auditing Mode

The Audit Trail System supports several object auditing modes.

ModeDescription
FullAll object changes are fully audited. This mode is the default.
LightweightOnly object creation, deletion and modification are audited. This mode does not audit names and values of changed properties.
CreationOnlyOnly object creation is audited. Intended for data import purposes.

To change the current object auditing mode, set the AuditTrailService.Instance.ObjectAuditingMode property to one of the ObjectAuditingMode enumeration values. The following code demonstrates how this can be implemented.

XAF Windows Forms Application - Program.cs (Program.vb) file:

XAF ASP.NET Application - Global.asax.cs (Global.asax.vb) file:

Expanded Audit the Current User or Host Identity

If you build a business application that is intended for use by several end-users at the same time, you need to get information on who made a particular change. For this purpose, the CurrentUserName property of the application's security system is passed to the Audit Trail system. If you do not use the XAF security system, in an XAF Windows Forms application you can get the user name from the WindowsIdentity object. In an XAF ASP.NET Web application, you can use the value returned by the HttpContext.Current.Request.UserHostAddress property. The following code demonstrates how this can be implemented.

Note

If you do not specify the current user for the Audit Trail system, the null value will be logged.

XAF Windows Forms Application - Program.cs (Program.vb) file:

XAF ASP.NET Application - Global.asax.cs (Global.asax.vb) file:

Expanded Specify the Objects and Properties to Be Audited

You can modify default audit settings, and specify objects and properties to be audited or excluded from the audit process. For this purpose, subscribe to the CustomizeAuditTrailSettings event of a AuditTrailService.Instance object. The following code demonstrates how this can be implemented.

XAF Windows Forms Application - Program.cs (Program.vb) file:

XAF ASP.NET Application - Global.asax.cs (Global.asax.vb) file:

Take note of the CustomizeAuditTrailSettings event handler. The default settings are removed by the AuditTrailSettings.Clear method. The properties to audit are added by the AuditTrailSettings.AddType method. You can use another overload of this method, which does not require specifying members names.

All members owned by the class, which are public and not read-only, will be audited. If MyObjectType exposes a read-only property to be audited, add it manually.

The AuditTrailSettings.RemoveProperties method is used to exclude properties from the audit process.

If you use Domain Components (DC), do not pass the DC interface type to the AddType method. Instead, pass the generated entity type.

You can use the CustomizeAuditTrailSettings event to customize the AuditTrailSettings object in other ways. For example, you can specify properties that are not to be audited. For this purpose, use the AuditTrailSettings.RemoveProperties method.

Expanded Customize the Data Storing Mechanism

By default, audit information is logged to the application database (see Audit Trail Module Overview). You can customize this process by handling the AuditTrailService.Instance.SaveAuditTrailData event, which is raised when an object is committed to the database. In this event handler, you have to replace the default saving mechanism of the AuditDataItem objects with a custom one. To disable the default storing procedure, you should set the handler's SaveAuditTrailDataEventArgs.Handled parameter to true. The following code demonstrates how this can be implemented.

XAF Windows Forms Application - Program.cs (Program.vb) file:

XAF ASP.NET Application - Global.asax.cs (Global.asax.vb) file.

Another way to customize the mechanism for storing audit information is to inherit from the AuditDataClass, and override the Save method. In this instance, you have to initialize the AuditTrailService.Instance.AuditDataStore property with an instance of your class.

Expanded Implement Custom Persistent Object to be Used as the Audit Data Store

By default, the AuditDataItemPersistent class is used as the audit data store. If you want to store extra audit information, inherit from this class, or implement the IAuditDataItemPersistent interface "from scratch". In the overridden OnSaving method of your AuditDataItemPersistent descendant, you can initialize extra properties based on the AuditedObject, PropertyName and other info from the base class. To use your custom class instead of the default one, set the AuditDataItemPersistentType property of the Audit Trail module in the Application Designer (not in the Module Designer).

Expanded Specify the String Representation of the Null Value

By default, the null value is saved as the "N/A" string. If you desire, you can change its string representation. For this purpose, use the AuditTrailService.Instance.AuditDataStore.NullValueString property.

Expanded Specify the String Representation of Reference Type Properties

Implement a descendant of the AuditDataStore class and override the GetDefaultStringRepresentation method. In addition, set the AuditTrailService.Instance.AuditDataStore property to an instance of your class.

Expanded Customize the Blob Properties Storage Mechanism

By default, Blob property values are not saved. The "Blob data" string is saved instead. You can customize this behavior by implementing the AuditDataStore class and overriding the Save method. In this instance, set the AuditTrailService.Instance.AuditDataStore property to an instance of your class.

Expanded Add Custom Data to the Audit Log

Object changes are represented by AuditDataItem objects (see Audit Trail Module Overview). You can add custom data (information on events that are not audited) to the audit log directly. This means that you can add an AuditDataItem object to the Audit Data Items collection. For this purpose, specify the following code.

This code can be implemented at any point in a program. For instance, in a custom Controller.

Note

You should always invoke the AuditTrailService.Instance.SaveAuditData method after adding custom audit data manually, without reusing the Session of the View's ObjectSpace. Otherwise, the audit data will not be written to the database.

Expanded See Also

How would you rate this topic?​​​​​​​