Orchardcore Audit Trail

Orchard Core Audit Trail - Prompt Templates

Configure Audit Trail and Event Tracking

You are an Orchard Core expert. Generate audit trail configurations, custom event providers, and AuditTrailPart setups for Orchard Core.

Guidelines

• Enable OrchardCore.AuditTrail for audit event recording.
• The Audit Trail provides an immutable, auditable log of system events (content changes, user events, etc.).
• Events are logged automatically for supported actions (create, publish, delete content items; user login failures, etc.).
• The audit trail list supports filtering by date range, category (Content, User, etc.), and sorting.
• Content events show version history, diffs, and allow restoring previous versions or deleted items.
• Restored content items are created as drafts that must be manually published.
• Attach AuditTrailPart to content types to let editors add comments to audit trail entries on save.
• Configure which events to record via Settings → Audit Trail.
• Client IP address logging is optional and may require GDPR/privacy compliance considerations.
• Trimming settings control how long events are retained in the database.
• Custom modules can provide their own audit trail event handlers.
• Always seal classes.

Enabling Audit Trail

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "OrchardCore.AuditTrail"
      ],
      "disable": []
    }
  ]
}

Audit Trail Event Categories

Audit Trail Event List Features

Attaching AuditTrailPart via Migration

using OrchardCore.ContentManagement.Metadata;
using OrchardCore.ContentManagement.Metadata.Settings;
using OrchardCore.Data.Migration;

namespace MyModule;

public sealed class AuditTrailMigrations : DataMigration
{
    private readonly IContentDefinitionManager _contentDefinitionManager;

    public AuditTrailMigrations(IContentDefinitionManager contentDefinitionManager)
    {
        _contentDefinitionManager = contentDefinitionManager;
    }

    public async Task<int> CreateAsync()
    {
        await _contentDefinitionManager.AlterTypeDefinitionAsync("{{ContentTypeName}}", type => type
            .WithPart("AuditTrailPart", part => part
                .WithPosition("20")
            )
        );

        return 1;
    }
}

Attaching AuditTrailPart via Recipe

{
  "steps": [
    {
      "name": "ContentDefinition",
      "ContentTypes": [
        {
          "Name": "{{ContentTypeName}}",
          "DisplayName": "{{DisplayName}}",
          "ContentTypePartDefinitionRecords": [
            {
              "PartName": "AuditTrailPart",
              "Name": "AuditTrailPart",
              "Settings": {
                "ContentTypePartSettings": {
                  "Position": "20"
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

Audit Trail Settings

Configure at Settings → Audit Trail:

Creating a Custom Audit Trail Event Provider

Implement IAuditTrailEventHandler to record custom events:

using OrchardCore.AuditTrail.Services;
using OrchardCore.AuditTrail.Services.Models;

namespace MyModule.AuditTrail;

public sealed class CustomAuditTrailEventHandler : AuditTrailEventHandlerBase
{
    public override Task CreateAsync(AuditTrailCreateContext context)
    {
        if (context is AuditTrailCreateContext<CustomAuditEvent> customContext)
        {
            customContext.AuditTrailEventItem.Action = "Created";
        }

        return Task.CompletedTask;
    }
}

public sealed class CustomAuditEvent
{
    public string Action { get; set; }
}

Recording a Custom Audit Trail Event

using OrchardCore.AuditTrail.Services;
using MyModule.AuditTrail;

namespace MyModule.Services;

public sealed class MyService
{
    private readonly IAuditTrailManager _auditTrailManager;

    public MyService(IAuditTrailManager auditTrailManager)
    {
        _auditTrailManager = auditTrailManager;
    }

    public async Task PerformActionAsync()
    {
        // Perform your action...

        // Record the audit trail event.
        await _auditTrailManager.RecordEventAsync(
            new AuditTrailContext<CustomAuditEvent>(
                name: "CustomAction",
                category: "MyModule",
                correlationId: "{{CorrelationId}}",
                userId: "{{UserId}}",
                userName: "{{UserName}}",
                auditTrailEventItem: new CustomAuditEvent()
            )
        );
    }
}

Registering Custom Audit Trail Event Handler

using OrchardCore.AuditTrail.Services;
using OrchardCore.Modules;

namespace MyModule;

public sealed class Startup : StartupBase
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddScoped<IAuditTrailEventHandler, CustomAuditTrailEventHandler>();
    }
}

Content Event Diff Tracking

The Audit Trail module tracks diffs between content versions:

• Current version values are shown in green.
• Previous version values are shown in red.
• Access diffs via the Details link → Diff tab in the audit trail list.

Audit Trail Trimming Configuration

{
  "steps": [
    {
      "name": "Settings",
      "AuditTrailTrimmingSettings": {
        "RetentionDays": 90,
        "Disabled": false
      }
    }
  ]
}

Enabling Content-Specific Audit Trail

To track specific content type events:

1. Navigate to Settings → Audit Trail → Content tab.
2. Select the content types to track.
3. Save the settings.

Only events for selected content types will be recorded, reducing noise in the audit log.

Best Practices

• Attach AuditTrailPart to critical content types (e.g., pages, policies) for edit comments.
• Enable IP logging only when required and ensure privacy compliance.
• Set a reasonable trimming period (e.g., 90–365 days) to manage database size.
• Use the Details/Diff view to investigate content changes before restoring.
• Custom event providers should use descriptive category and event names for easy filtering.