Records and Events

Open a transaction to compare its values, or expand “View 2 changes” to inspect the individual changes.

Audit records retain stable identities, raw before/after values and user metadata. One transaction can contain several cell changes.

What Gets Recorded

Each top-level audit item is an AuditRecord. A record contains one transaction ID and one or more AuditChange entries.

{
  id: 'audit-001',
  transactionId: 'tx-001',
  type: 'cell-change',
  changedAt: '2026-05-08T12:00:00Z',
  changedBy: {
    id: 'avery-stone',
    email: '[email protected]',
  },
  changes: [
    {
      id: 'change-001',
      rowId: 'invoice-123',
      rowType: 'rgRow',
      column: 'status',
      oldValue: 'Draft',
      newValue: 'Approved',
    },
  ],
}

For a paste operation, the same record can contain many changes:

{
  transactionId: 'tx-002',
  type: 'bulk-paste',
  changedAt: '2026-05-08T12:05:00Z',
  changedBy: { id: 'avery-stone' },
  changes: [
    {
      id: 'change-002',
      rowId: 'invoice-123',
      rowType: 'rgRow',
      column: 'status',
      oldValue: 'Draft',
      newValue: 'Approved',
    },
    {
      id: 'change-003',
      rowId: 'invoice-124',
      rowType: 'rgRow',
      column: 'status',
      oldValue: 'Draft',
      newValue: 'Rejected',
    },
  ],
}

Application Events and Snapshots

Use recordEvent for application-driven records that do not come from direct grid editing:

auditHistoryPlugin?.recordEvent({
  type: 'api-sync',
  changedBy: { id: 'webhook', name: 'Webhook' },
  presentation: {
    source: 'api',
    targetLabel: 'F1:F8',
    detailLabel: '8 cells recalculated',
  },
});

Custom action types are plain strings. When the record carries normal cell or row changes, existing restore helpers can use it for revert workflows:

auditHistoryPlugin?.recordEvent({
  type: 'approval-submitted',
  transactionId: 'approval-42',
  changedBy: currentUser,
  changes: [{
    rowId: 'invoice-123',
    rowIndex: 0,
    rowType: 'rgRow',
    column: 'status',
    oldValue: 'Draft',
    newValue: 'Approved',
  }],
  presentation: {
    source: 'api',
    verb: 'submitted approval',
    targetLabel: 'Invoice 123',
  },
});

auditHistoryPlugin?.restoreTransaction('approval-42');

Summary-only custom records are ignored unless you opt in with allowEmpty: true.

Use snapshots when users need a named restore point:

const snapshot = auditHistoryPlugin?.createSnapshot('Before Q4 close');
if (snapshot) {
  auditHistoryPlugin?.restoreSnapshot(snapshot);
}

See restore workflows for recovery and localization for record presentation labels.