Audit Log
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Recording, viewing, filtering, exporting, and access control for audit trail data Domain: AUDIT
Statement
The system shall maintain and display a comprehensive audit log of all recorded changes, providing users with the ability to view, filter, and export audit trail data for compliance and accountability purposes.
The audit log supports multi-site deployments with site-based access controls, ensuring users only see audit entries for sites they have permission to access. All audit data is immutable once recorded, and users can export filtered audit data to Excel format for external analysis and compliance reporting.
Behavior Overview (Illustrative)
This diagram illustrates the high-level behavior. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Audit Entry | A single record capturing a change event including timestamp, user, area affected, and before/after values |
| Change Type | Classification of the modification (e.g., create, update, delete) |
| Area | The system module or functional area where the change occurred |
| Site | A deployment location in multi-site configurations; users may have access to one or more sites |
Functional Requirements
Audit Data Viewing (REQ-AUDIT-001)
FR-AUDIT-001 Display Audit Trail
The system shall display a comprehensive log of all recorded changes in reverse chronological order.
Acceptance Criteria:
Display Content:
- Display audit entries with: timestamp, user, area, change type, action, change location, value before, and value after
- Present audit data in read-only format
- Display all columns by default; users may hide columns via configuration
Sorting and Pagination:
- Sort entries by timestamp descending (newest first)
- Enforce a fixed reverse chronological sort order that users cannot change
- Provide pagination controls for navigating large datasets
- Provide standard pagination controls including page navigation and items per page selection
- Display record count indicating current view position (e.g., "Showing x-y out of z")
User Interaction:
- Allow users to customize visible data columns
- Allow users to refresh the display to retrieve latest entries
- Preserve active filter selections during refresh operations
Trace: Source: 3.0.0-Audit log (Rows 1, 2, 3, 8, 9, 11) | Jira: BT-1923 | Tests: BT-2480 | Epic: BT-2332
Audit Data Filtering (REQ-AUDIT-002)
FR-AUDIT-002 Filter Audit Entries
The system shall allow users to constrain displayed audit entries using filter criteria.
Acceptance Criteria:
Date Filtering:
- Support date filtering by single date or date range
- Support both single date and date range selection for date filtering
Categorical Filtering:
- Support categorical filtering by: Actions, Areas, Change Types, Usernames
- Support multi-select within each categorical filter
- Use multi-select dropdown controls for categorical filters
Filter Behavior:
- Support combining multiple filter criteria
- Provide a mechanism to reset filters to default values
- Allow toggling filter visibility without clearing active filters
- Filters shall be visible by default when the view loads
- Preserve and continue to apply active filter selections when filters are hidden
Trace: Source: 3.0.0-Audit log (Rows 4, 5, 6, 7, 12) | Jira: BT-1923, BT-2661 | Tests: BT-2480 | Epic: BT-2332
Audit Data Export (REQ-AUDIT-003)
FR-AUDIT-003 Export Audit Data
The system shall allow users to export audit log data for external analysis and compliance reporting.
Acceptance Criteria:
Export Format:
- Export audit data in Excel format
- Deliver the export file via email with download link
- Exported data shall include all data columns regardless of current visibility settings
- Exported data shall respect active filter criteria (only filtered entries exported)
Error Handling:
- Export generation fails: The system shall notify the user of the failure and provide retry option
- Email delivery fails: The system shall log the failure and allow manual export retrieval
Resolved Questions:
- Maximum export size: No maximum limit. User must be able to export entire audit log. Queued background job can long-run; chunking required for large exports.
- Download link validity: 7 days, then deleted
Trace: Source: 3.0.0-Audit log (Row 10) | Jira: BT-1923 | Tests: BT-1509, BT-1508 | Epic: BT-2332
Multi-Site Access Control (REQ-AUDIT-004)
FR-AUDIT-004 Enforce Site-Based Access Control
The system shall restrict audit log visibility based on the user's site access permissions.
Acceptance Criteria:
Visibility Restrictions:
- Display audit entries only for sites the user has access to
- Restrict site filter options to only sites the user has access to
- Prevent users from viewing audit transactions for sites they cannot access
Site Column Display:
- Display a site identifier column for users with multi-site access
- Position the site column between User and Area columns
- Display the site column only to users with manager role or multi-site access
Assumptions:
- User site access permissions are maintained by the user management system
Trace: Source: 3.0.0-Audit log (Rows 13, 14, 15) | Jira: BT-3035 | Tests: BT-2480 | Epic: BT-2332
Configuration Options
Verified: Configuration options confirmed via code inspection (AuditsController.php, config/database.php).
| Option | Default | Description | Affects |
|---|---|---|---|
| per_page | 10 | Number of audit entries per page (request parameter) | REQ-AUDIT-001 |
| DB_AUDIT_CONNECTION | mysql_audit | Database connection name for audit storage | REQ-AUDIT-001 |
| DB_AUDIT_HOST | 127.0.0.1 | Audit database host | REQ-AUDIT-001 |
| DB_AUDIT_PORT | 3306 | Audit database port | REQ-AUDIT-001 |
| DB_AUDIT_DATABASE | vapor_audit | Audit database name | REQ-AUDIT-001 |
| DB_AUDIT_USERNAME | vapor | Audit database username | REQ-AUDIT-001 |
| DB_AUDIT_PASSWORD | (empty) | Audit database password | REQ-AUDIT-001 |
| DB_AUDIT_SOCKET | (empty) | Unix socket for audit database connection | REQ-AUDIT-001 |
Assumptions
- Users accessing the Audit Log have appropriate role permissions
- All system modules emit audit events for trackable changes
- Audit data is immutable once recorded
- Network connectivity is available for data retrieval and export operations
UI Notes (Illustrative)
FR-AUDIT-001 UI Specifications
Table Layout:
- Standard table component with columns: Date, Time, User, Area, Change Type, Action, Change Location, Value Before, Value After
- Data displayed in read-only tabular format
- Row count display format: "Showing x-y out of z"
Visual Elements:
- Refresh icon for manual data refresh
- Column visibility configuration accessible via button/dialog
Interaction:
- Standard table navigation using shared Tables component patterns
- Page navigation controls: next, previous, page numbers, items per page selector
FR-AUDIT-002 UI Specifications
Filter Layout:
- Filter section collapsible via Show/Hide button
- Date filter and dropdown filters follow shared Filters component patterns
Interaction:
- Reset button clears all filters to default state
- Show/Hide toggle preserves filter state while hiding the filter UI
FR-AUDIT-003 UI Specifications
Export Interaction:
- Download/export icon initiates export process
- User receives email notification with download link upon completion
FR-AUDIT-004 UI Specifications
Site Column:
- Site column positioned between User and Area columns
- Shows the site where changes were made
Implementation (Illustrative)
| Component | Location | Requirements | Description |
|---|---|---|---|
| Model | App\Audit | REQ-AUDIT-001, REQ-AUDIT-003 | Audit record model for immutable audit trail entries |
| Controller | AuditsController@index | REQ-AUDIT-001, REQ-AUDIT-002 | Query and display paginated audit log entries |
| Controller | AuditExportsController@store | REQ-AUDIT-003 | Initiate audit export job |
| Job | AuditExportJob | REQ-AUDIT-003 | Background processing for chunked audit data export with email delivery |
| Event Interface | AuditableEvent | REQ-AUDIT-001 | Interface defining audit event structure (username, area, change_type, action, etc.) |
| Listener | LogIntoDatabase | REQ-AUDIT-001 | Central listener that persists AuditableEvent implementations to audit storage |
| Filter | AuditFilters | REQ-AUDIT-002, REQ-AUDIT-004 | Filter logic for date range, actions, areas, change types, usernames, sites |
| Action | GetAuditsAction | REQ-AUDIT-001, REQ-AUDIT-002 | Encapsulates audit query with filtering and pagination |
| QueryBuilder | AuditQueryBuilder | REQ-AUDIT-004 | Site-based query scoping for multi-site access control |
| Controller | AuditActionsController@index | REQ-AUDIT-002 | Provides distinct action values for filter dropdown |
| Controller | AuditAreasController@index | REQ-AUDIT-002 | Provides distinct area values for filter dropdown |
| Controller | AuditChangeTypesController@index | REQ-AUDIT-002 | Provides distinct change type values for filter dropdown |
| Controller | AuditUsernamesController@index | REQ-AUDIT-002 | Provides distinct username values for filter dropdown |
| Controller | AuditCreatedAtRangeController@index | REQ-AUDIT-002 | Provides min/max date range for date filter |
| Controller | AuditSiteNamesController@index | REQ-AUDIT-004 | Provides site names restricted to user's visible sites |
Implementation (Frontend, Illustrative)
| Component Type | Location |
|---|---|
| View | views/Audits.vue |
| Components | components/audits/ |
| Store | store/modules/auditOptions.js |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-AUDIT-001 | Display Audit Trail | Test | Audit, AuditsController, GetAuditsAction, AuditableEvent, LogIntoDatabase | BT-2480 | Draft |
| REQ-AUDIT-002 | Filter Audit Entries | Test | AuditsController, AuditFilters, AuditFilterOptions/* | BT-2480 | Draft |
| REQ-AUDIT-003 | Export Audit Data | Test | AuditExportsController, AuditExportJob, Audit | BT-1509, BT-1508 | Draft |
| REQ-AUDIT-004 | Enforce Site-Based Access Control | Test | AuditFilters, AuditQueryBuilder, AuditSiteNamesController | BT-2480 | Draft |
Notes
- Audit Log references standard Tables requirements for pagination behavior
- Audit Log references standard Filters requirements for date and dropdown behavior
- The audit data is immutable; no edit or delete operations are supported on audit entries
Open Questions
None - all questions resolved.
Acceptance Tests
Test: REQ-AUDIT-001
Test: Verify audit table structure
Given: User navigates to the Audit page
When: The audit log view loads
Then: The system shall display columns: Date, Time, User, Area, Change Type, Action, Change Location, Value Before, Value After
And: The data shall be read-only
And: The data shall be sorted by date/time descending (newest first)
Test: Verify row count display
Given: User is on the Audit page
When: The audit log view loads
Then: The system shall display record count in "Showing x-y out of z" format
Test: Verify pagination
Given: User is on the Audit page with more than one page of results
When: User navigates to next/previous page
Then: The system shall display the corresponding page of results
Test: Verify column visibility configuration
Given: All columns are shown by default on the Audit table
When: User opens column visibility configuration
And: User deselects some columns
And: User confirms the selection
Then: The system shall hide the deselected columns from the table
Test: Verify table refresh
Given: User is on the Audit page with filters applied
When: User initiates a refresh
Then: The system shall reload the audit data with latest entries
And: The system shall preserve current filter selections
Test: REQ-AUDIT-002
Test: Verify default filter state
Given: User navigates to the Audit page
When: The page loads
Then: The filter section shall be visible by default
Test: Verify filter visibility toggle
Given: User is on the Audit page with filters visible
When: User toggles filter visibility
Then: The filter section shall be hidden
And: Active filter selections shall continue to apply
When: User toggles filter visibility again
Then: The filter section shall be visible
And: Previously selected filter values shall be preserved
Test: Verify date filter
Given: User is on the Audit page
When: User filters by a single date
Then: The system shall display only audit entries from that date
When: User filters by a date range
Then: The system shall display only audit entries within that date range
Test: Verify categorical filters
Given: User is on the Audit page
When: User selects one or more values in the Actions filter
Then: The system shall display only audit entries with the selected actions
When: User selects one or more values in the Areas filter
Then: The system shall display only audit entries from the selected areas
When: User selects one or more values in the Change Types filter
Then: The system shall display only audit entries with the selected change types
When: User selects one or more values in the Usernames filter
Then: The system shall display only audit entries by the selected users
Test: Verify filter reset
Given: User is on the Audit page with filters applied
When: User resets filters
Then: The system shall reset all filters to default values
And: The system shall display unfiltered data
Test: REQ-AUDIT-003
Test: Verify export initiation
Given: User is on the Audit page
When: User initiates an export
Then: The system shall begin the export process
And: The system shall send an email to the user with a download link
Test: Verify export includes all columns
Given: User has hidden some columns on the Audit page
When: User exports to Excel
Then: The exported file shall contain all columns including hidden columns
Test: Verify export respects filters
Given: User has filters applied on the Audit page
When: User exports to Excel
Then: The exported file shall contain only rows that match the current filters
Test: REQ-AUDIT-004
Test: Verify site column for multi-site users
Given: User has access to multiple sites
When: User opens the Audit page
Then: The system shall display a Site column between User and Area columns
And: The Site column shall show the site where each change was made
Test: Verify site filter access restriction
Given: User A has access to Site 1 only
And: User B has access to Site 1 and Site 2
When: User A opens the site filter
Then: User A shall only see Site 1 as an option
And: Site 2 shall not be visible
When: User B opens the site filter
Then: User B shall see Site 1 and Site 2 as options
Test: Verify audit visibility restriction
Given: User A has access to Site 1 only
And: User B has access to Site 1 and Site 2
When: User A views the audit trail
Then: User A shall see only audit transactions for Site 1
And: User A shall not see transactions for Site 2
When: User B views the audit trail
Then: User B shall see audit transactions for both Site 1 and Site 2
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Architecture | Aurora database for immutable audit record storage, Amazon SES for export download link delivery, Amazon SQS for background job queuing |
| SDD Security | Authorization-based visibility restrictions on audit data |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion)
- UI details are fully demoted to Illustrative section
- Configuration options are not encoded as requirements
- Acceptance criteria describe behavior, not UI mechanics
- Every requirement has acceptance criteria and source traceability
- Error handling addressed for I/O, validation, and external system requirements
- Open questions documented with owners assigned (all resolved)
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- Refinements folded into acceptance criteria
- Traceability matrix is complete
Reviewer Notes
Consolidation: REQ-AUDIT-001
The following items from the source were consolidated into a single display capability requirement:
| Original Item | Source Reference | Disposition |
|---|---|---|
| REQ-AUDIT-001 (Display audit log) | 3.0.0-Audit log (Rows 1, 2, 3, 11) | Merged -> REQ-AUDIT-001 Statement |
| REQ-AUDIT-003 (Column visibility) | 3.0.0-Audit log (Row 8) | Merged -> REQ-AUDIT-001 AC |
| REQ-AUDIT-004 (Refresh) | 3.0.0-Audit log (Row 9) | Merged -> REQ-AUDIT-001 AC |
Rationale: Column visibility and refresh are interaction conveniences of the display capability, not separate system responsibilities. They enhance how users interact with the displayed audit data but do not constitute independent capabilities.
Reversibility: To restore original structure, reference:
- Source:
output/pilot/restructured/audit-log.md - Confluence: 3.0.0-Audit log (Rows 1-11)
ID Renumbering
Due to consolidation, the following IDs were renumbered:
| Original ID | New ID | Reason |
|---|---|---|
| REQ-AUDIT-001 | REQ-AUDIT-001 | Retained (consolidated target) |
| REQ-AUDIT-002 | REQ-AUDIT-002 | Retained |
| REQ-AUDIT-003 | (consolidated) | Merged into REQ-AUDIT-001 |
| REQ-AUDIT-004 | (consolidated) | Merged into REQ-AUDIT-001 |
| REQ-AUDIT-005 | REQ-AUDIT-003 | Renumbered (Export) |
| REQ-AUDIT-006 | REQ-AUDIT-004 | Renumbered (Multi-site) |
Refinements Folded into Acceptance Criteria
The following refinements were converted to acceptance criteria and added to their parent requirements:
REQ-AUDIT-001:
| Original ID | Content |
|---|---|
| RF-01 | Sort order constraint |
| RF-02 | Default column visibility |
| RF-03 | Standard pagination controls |
REQ-AUDIT-002:
| Original ID | Content |
|---|---|
| RF-01 | Date filter selection modes |
| RF-02 | Multi-select dropdown pattern |
| RF-03 | Hidden filter state preservation |
REQ-AUDIT-004:
| Original ID | Content |
|---|---|
| RF-01 | Site column positioning |
| RF-02 | Site column visibility conditions |