Audit Trail¶
The audit trail logs all changes to records in the system. It ensures complete traceability of all editing operations and is a central requirement for compliance with quality standards such as ISO 17025.
Overview¶
The audit trail automatically captures every creation, modification, and deletion of records. The timestamp, the executing user, as well as the old and new values are stored.
Monitored Areas¶
Each area is maintained in a separate audit table. The column display is loaded dynamically based on roles.
| Area | Table | Description |
|---|---|---|
| Inventory | inventory_audit |
Changes to inventory records. |
| Bookings | booking_audit |
Changes to booking records. |
| Customers | customers_audit |
Changes to customer master data. |
| Maintenance / Repair | repair_audit |
Changes to maintenance and repair orders. |
Columns¶
| Column | Description |
|---|---|
| Timestamp | Date and time of the change. |
| User | Name of the user who made the change. |
| Type | Type of change (INSERT, UPDATE, DELETE). |
| Field Name | Name of the changed field. |
| Old Value | Value before the change. |
| New Value | Value after the change. |
| Table | Affected data area (e.g., inventory, calibration). |
| Record ID | Unique identifier of the affected record. |
Access¶
The audit trail is accessible in various areas of the system:
- Inventory details: Under the Status History tab, all changes to the respective inventory are displayed.
- Customer details: Changes to the customer record and associated contacts.
- Booking details: Changes to individual booking processes.
Typical Usage Scenarios¶
- Change tracking: Checking who made which changes to a device record and when.
- Quality audit: Proof of complete documentation for external audits and certifications.
- Error analysis: Identification of erroneous changes and tracing back to the originator.
- Status history: Tracking the status changes of an inventory item over its entire lifecycle.
Technical Notes¶
Automatic Capture
The audit trail is automatically populated with every data change. No manual action is required. System-internal changes are logged with the user "SYSTEM".
Immutability
Audit trail entries are part of the revision-proof documentation. Changes to the audit trail itself should only be made by authorized personnel.
- Status fields are automatically translated into readable labels (e.g., inventory status, booking status).
- The view supports filtering by user, time period, change type, and field name.
- The displayed column configuration is role-dependent and loaded dynamically via AJAX.
- Access requires the permission
inventory_details_statushistory_view.
Retention and Archive¶
The audit trail grows with every change and never shrinks unless something cleans it up. On an actively used installation, tens of thousands of entries accumulate per day. calServer therefore keeps it in two stages.
| Stage | Table | Purpose |
|---|---|---|
| Hot window | audit |
The recent past, behind the grid and the detail pages. Default: 24 months. |
| Archive | audit_archive |
Everything older. Same columns, fewer indexes, rarely read. |
Moving an entry to the archive deletes nothing. An entry leaves the system only once the legal retention period has expired.
Configuring the retention period¶
The period applies to audit entries and device data alike and varies by laboratory, accreditation, and customer contract. The configurable range is 10 to 30 years, with 10 as the default.
It is maintained under Administration > General settings > Retention.
| Field | Meaning | Default |
|---|---|---|
| Retention period (years) | When an archived entry may be deleted (10-30). | 10 |
| Audit trail: hot window (months) | How long an entry stays in the hot window. | 24 |
The minimum period cannot be undercut
A value below 10 years is raised to 10, a value above 30 is capped at 30. The hot window is additionally bounded by the retention period.
The cleanup run¶
The scheduled task Archive audit trail (audit:prune) runs daily at 4 a.m.
It first moves everything past the hot window into the archive, then deletes
from the archive whatever is past the retention period.
# Dry run: reports what would move and what would be deleted
docker exec calserver-api-v2 php artisan audit:prune --dry-run
The first run takes a while
On a grown installation the first run moves a great many rows. It works in batches and can be interrupted and repeated safely -- the next run picks up where the previous one left off.
Creation and deletion in the trail¶
When a record is created or deleted, calServer writes one entry containing all fields as a snapshot -- not one entry per field. The view unfolds it back into individual fields, so the content is the same.
Two practical consequences:
- The field name filter matches changes only, not creations or deletions. Those are filtered via the change type instead.
- In an unfolded snapshot, references to other records appear as identifiers rather than names. The identifier is shown shortened, with the full value in the tooltip.