The AuditLog kit — the app's audit log, as a page of its settings

use Osysharp.AuditLog@0; · policy ReadsAuditLog => …; · AuditLogLines(since) · AuditLogList(shown, capped, nothingYet) · component AuditLogSettings

`Osysharp.AuditLog` is a default audit log page an app mounts with one line. It reads the platform's change trail (`EntityAuditRecord`) as the reader may read it — the app's own `app.Audit` read rule decides the rows — and shows each change with its old and new values, who made it and when, newest first, narrowed by period, kind of record and person. It sits among the app's settings at `/settings/audit`.

Summary#

The platform keeps the change trail and the app says who may read it (audit read access (app.Audit)). use Osysharp.AuditLog@0; is the page that reads it, and the whole of mounting it:

app Garden { use Osysharp.AuditLog@0; }                       // the page, and its link among the settings
app.Audit = new AuditConfig {                                 // who reads the trail — said once, as before
  EntityAuditRecord = new AuditSurface { Read = user => IsSteward },
};

Signature#

use Osysharp.AuditLog@0;                     // brings Osysharp.Observability and Osysharp.Ui with it

policy ReadsAuditLog => <who may open the page>;          // optional — anybody signed in by default

List<AuditLogLine> AuditLogLines(DateTime since)          // the changes since then that the reader may read, newest first
AuditLogList(List<AuditLogLine> shown, bool capped, bool nothingYet)   // the list the page draws
component AuditLogSettings                                // the page at /settings/audit — an app's own of that name replaces it

Description#

The trail's own rule decides the rows#

The kit adds no access of its own. It reads EntityAuditRecord like any other entity, so the rows are the ones the app's app.Audit.EntityAuditRecord.Read gives the reader, and no others. An app that opens the trail to admins for its settings alone gets a log of its settings alone. ReadsAuditLog says only who may open the page.

Offered to whoever may read it#

The page announces itself as a settings section (ISettingsProvider and [OrgPolicy]: kits announce their settings, and a setting says whether an organisation may govern it). Its link is shown to somebody the trail's rule lets read at least one change, asked as that reader. Somebody else is not offered the page, and opening it by its address shows "No changes you may read".

Each change, said#

A line names the kind of record ("Opening hours" from OpeningHours) and the record itself, from its Name, Title, DisplayName, Label, Code or Email. A change that did not touch the name, and a removal, are named from the record's other changes. A change lists each field from what to what. A reference says only that it moved, because its ids say nothing to a reader. A value the app redacts reads ‹redacted› ([[config-audit#redaction]]). A change nobody made, such as a workflow or the app's starting data, is "by The app itself".

Narrowed on the page#

The page reads a year of changes, at most the newest 200, and narrows them by period (7, 30 or 90 days, or a year), by kind of record and by person. When the read stopped at its limit, it says so.

Examples#

A garden's log#

```osy title="the log mounted by its use line, the trail opened to everybody" test app=ui-audit-log-kit app Garden { use Osysharp.AuditLog@0; model "model/**/*.osy"; }

// Nobody signs in to this example, so everybody opens the page and reads the trail. A real app names its people: // policy ReadsAuditLog => IsAdmin;, Read = user => IsSteward. policy ReadsAuditLog => true;

[Title(Name)] entity Plot { [Required, MaxLength(80)] string Name; int SquareMetres; security { allow read, create, update, delete when IsAnonymous || IsAuthenticated; } }

app.Audit = new AuditConfig { EntityAuditRecord = new AuditSurface { Read = user => true }, };


```osy title="a resize, said with its values and the plot's name" run app=ui-audit-log-kit
[Test]
void A_change_is_said_with_its_values() {
  var plot = new Plot { Name = "North bed", SquareMetres = 10 };
  UnitOfWork.Commit();
  plot.SquareMetres = 14;
  UnitOfWork.Commit();
  var changed = AuditLogLines(DateTime.UtcNow.AddDays(-1)).Single(l => l.Happened == "Changed");
  Assert.Equal("North bed", changed.Name);
  Assert.Contains("Square metres: 10 → 14", changed.Fields);
}