Notification Indicators
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Runfile notification indicators on Run Page and Runfile List Domain: NOTIF
Statement
The system shall display notification indicators showing counts of wells in each status category for a runfile.
These indicators provide a quick run-status overview and may be used to filter wells by status. Administrators can configure whether system-generated comments are included in comment counts.
Behavior Overview (Illustrative)
This diagram illustrates the high-level behavior. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Notification Icon | A visual indicator showing a count of wells in a specific status category |
| Associate Control Error | A specific error type tracked separately from general well errors |
| System-Generated Comment | A comment automatically created by the system (e.g., "exported") rather than entered by a user |
| Label Error | An error type indicating wells with labeling discrepancies |
Status Categories
When the user hovers over a notification indicator, the system displays the corresponding status category label:
- Unrecognised wells — Wells that cannot be matched to expected identifiers or configuration.
- Error wells — Wells that violate error-level rules or constraints.
- Warnings — Wells that violate warning-level rules but are not errors.
- Exportable wells — Wells eligible for export based on configuration and evaluation.
- Commented wells — Wells with one or more comments associated with them.
Special Categories:
- Associate Control Error — A specific error type tracked separately from general error counts. Uses a distinct icon and is not included in the general Error count.
- Label Error — Wells with labeling discrepancies, displayed per-mix in expanded views.
Functional Requirements
Status Display (REQ-NOTIF-001)
FR-NOTIF-001 Indicator Display
The system shall display one indicator per supported status category showing the count of wells in that category.
Acceptance Criteria:
- Display notification counts in runfile list views
- Display notification counts on individual runfile pages
- Show the count of wells matching each category
- Provide category identification for each notification
- Support categories: unrecognised wells, error wells, warnings, exportable wells, commented wells
Trace: Source: 3.0.0-Notifications (Rows 1, 2) | Jira: BT-990, BT-30 | Tests: BT-2727
Interactive Filtering (REQ-NOTIF-002)
FR-NOTIF-002 Filter by Notification Selection
The system shall allow users to filter the wells display by selecting a notification category with a non-zero count.
Acceptance Criteria:
- Notification categories with counts greater than zero shall be selectable
- The system shall indicate which notifications are selectable
- Selecting a notification shall filter the wells display to show only wells matching that category
- The filtered display shall update to show only matching wells
Trace: Source: 3.0.0-Notifications (Rows 3, 4) | Jira: BT-2359, BT-30 | Tests: BT-2473 | Related: REQ-NOTIF-001
Special Error Categories (REQ-NOTIF-003)
FR-NOTIF-003 Associate Control Error Separation
The system shall display Associate Control Error notifications as a distinct category separate from general error counts.
Acceptance Criteria:
- Display Associate Control Error count in runfile list notifications
- Display Associate Control Error count on individual runfile pages
- Do NOT include Associate Control Error counts in the general Error count
- Show Associate Control Error notifications to all user roles (Junior, Senior, Super Admin)
Trace: Source: 3.0.0-Notifications (Rows 5, 6) | Jira: BT-3734 | Tests: BT-3836
Comment Counting (REQ-NOTIF-004)
FR-NOTIF-004 Configure Comment Counting Behavior
The system shall allow administrators to configure whether system-generated comments are included in notification comment counts.
Acceptance Criteria:
- A configuration option shall control whether system-generated comments are counted
- When disabled, count only user-created comments
- When enabled, count all active comments (including system-generated)
- Deleted comments shall not be counted regardless of configuration
- Edited comments shall count as one comment (not multiple)
- Display comment counts in runfile list and individual runfile pages
Trace: Source: 3.0.0-Run Notifications - Comments count include/exclude system generated comments (Rows 1, 2, 3) | Jira: BT-4311 | Tests: BT-4328 | Epic: BT-4306
Mix-Level Notifications (REQ-NOTIF-005)
FR-NOTIF-005 Mix-Specific Label Error Counts
The system shall display label error counts per mix when viewing expanded runfile details.
Acceptance Criteria:
- Expanded runfile views shall show per-mix notification information
- Each mix shall display its label error count
- Label error count shall include only Label Error type errors for that mix
- Non-Label Errors shall not be included in this count
Trace: Source: 3.0.0-Run Analyze: Show Run Mix Wise 'Label Errors Count' (Row 1) | Jira: BT-4108 | Tests: BT-4119 | Epic: BT-4101
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
count_system_generated_comments | true | Whether system-generated comments are included in comment notification counts | REQ-NOTIF-004 |
Assumptions
- Users have at minimum Junior User role permissions to view notifications
- Runfiles contain wells with categorizable status information
- Notification categories are predefined by the system (unrecognised, error, warning, exportable, commented)
- Administrators have appropriate permissions to modify comment counting configuration
UI Notes (Illustrative)
FR-NOTIF-001 UI Specifications
- Display locations: notification icons in Runs Table notifications column; notification icons at top of Run Page
- Icons with zero count may be displayed differently or hidden
- Hovering over an icon displays a tooltip with the category name
FR-NOTIF-002 UI Specifications
- Clickable icons have a visual indicator (e.g., underlined number)
- Icons with count of zero are not clickable
FR-NOTIF-003 UI Specifications
- Associate Control Error uses a specific designated icon (distinct from general error icon)
- Icon displayed in both Runs Table notifications column and Run Page notification section
FR-NOTIF-005 UI Specifications
- Label error counts displayed in expanded runfile row sub-rows (per mix)
- Uses Label Errors icon to indicate notification type
Implementation (Illustrative)
The NOTIF requirements describe runfile status notification display, which is primarily a frontend concern. The backend provides well state data through the following components:
| Component | Type | Path | Requirements |
|---|---|---|---|
| Well | Model | code/app/Well.php | REQ-NOTIF-001, REQ-NOTIF-002, REQ-NOTIF-003, REQ-NOTIF-005 |
| ErrorCode | Model | code/app/ErrorCode.php | REQ-NOTIF-001, REQ-NOTIF-003, REQ-NOTIF-005 |
| Comment | Model | code/app/Comment.php | REQ-NOTIF-004 |
| GetRunStatus | Service | code/app/GetRunStatus.php | REQ-NOTIF-001, REQ-NOTIF-002 |
| ClientConfiguration | Model | code/app/ClientConfiguration.php | REQ-NOTIF-004 |
Note: The notification counts and filtering UI are implemented in the Vue.js frontend (components/app-notifications/). Backend provides the raw well/error data which the frontend aggregates and displays.
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-NOTIF-001 | Display Runfile Status Notifications | Test | Well, ErrorCode, GetRunStatus; Frontend | BT-2727 | Draft |
| REQ-NOTIF-002 | Filter Runfile by Notification Selection | Test | Well, ErrorCode, GetRunStatus; Frontend | BT-2473 | Draft |
| REQ-NOTIF-003 | Display Associate Control Error Notifications | Test | Well, ErrorCode (ERROR_TYPE constants) | BT-3836 | Draft |
| REQ-NOTIF-004 | Configure Comment Counting Behavior | Test | Comment.is_system_generated, ClientConfiguration | BT-4328 | Draft |
| REQ-NOTIF-005 | Display Mix-Specific Label Error Counts | Test | Well, ErrorCode, Run mix relationships | BT-4119 | Draft |
Notes
- Notification icons provide at-a-glance status for runfiles
- Associate Control Errors are tracked separately to distinguish from other well errors
- The deletion audit trail comment ("I deleted this comment.") may still be counted in comment notifications
- Label errors may indicate wells with labeling discrepancies
- Reference: REM Assay Summary (Reqs 7-9) for related filtering behavior
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| OQ-001 | Assumptions inferred from context, not explicitly stated in source. Confirm accuracy with SME. | Assumptions | @SME-TBD | TBD |
Acceptance Tests
Test: REQ-NOTIF-001
Test: Verify notification display in Runs Table
Given: User navigates to Run Files page
When: User observes the Notifications column
Then: Notification indicators shall be visible for each runfile row
And: Indicators shall display counts for relevant categories
Test: Verify notification category identification
Given: User on Run Files page or Run Page
When: User requests identification of notification category for unrecognised wells
Then: Category shall be identified as "Unrecognised wells"
When: User requests identification of notification category for error wells
Then: Category shall be identified as "Error wells"
When: User requests identification of notification category for warnings
Then: Category shall be identified as "Warnings"
When: User requests identification of notification category for exportable wells
Then: Category shall be identified as "Exportable wells"
When: User requests identification of notification category for commented wells
Then: Category shall be identified as "Commented wells"
Test: REQ-NOTIF-002
Test: Verify selectable notifications
Given: Run with 5 unrecognised wells, 3 error wells, 0 warnings
When: User observes notification indicators
Then: Unrecognised wells indicator shows count 5 and is selectable
And: Error wells indicator shows count 3 and is selectable
And: Warnings indicator shows count 0 and is not selectable
Test: Verify filter application on selection
Given: User on Run Page with notification indicators
And: Run has 5 unrecognised wells out of 96 total wells
When: User selects the unrecognised wells notification
Then: The wells display shall be filtered to unrecognised wells
And: Only the 5 unrecognised wells shall be displayed
Test: REQ-NOTIF-003
Test: Verify Associate Control Error in Runs Table
Given: Run A with Well A1 having Error Type: Associate Control Error
When: User views the Runfile list
Then: Runs Table shall show Run A
And: Notifications shall include Associate Control Error with count 1
Test: Verify Associate Control Error in Run Page
Given: Run A with Well A1 having Error Type: Associate Control Error
When: User opens Runfile and views notifications
Then: Associate Control Error notification shall show count 1
Test: Verify Associate Control Error excluded from general Error count
Given: Run A with:
Well A1 with Error Type: Associate Control Error
Well A2 with Error Type: Standard Error
When: User views notifications for Run A
Then: Associate Control Error count shall be 1
And: General Error count shall be 1 (not 2)
Test: REQ-NOTIF-004
Test: Verify comment count with system comments disabled
Given: Configuration "Count system generated comments" is false
And: Run 1 with Well A1 (user comment: "sample comment") and Well A2 (system comment: "exported")
When: User views runfile list
Then: Run 1 notifications shall indicate 1 comment
When: User opens Run 1
Then: Notifications shall indicate 1 comment
Test: Verify comment count with system comments enabled
Given: Configuration "Count system generated comments" is true
And: Run 1 with Well A1 (user comment: "sample comment") and Well A2 (system comment: "exported")
When: User views runfile list
Then: Run 1 notifications shall indicate 2 comments
When: User opens Run 1
Then: Notifications shall indicate 2 comments
Test: Verify deleted comments not counted
Given: Run with Well A1 (no comments)
When: User adds comment "test comment" on A1
Then: Run notification shall indicate 1 comment
When: User edits comment to "test comment edited"
Then: Run notification shall indicate 1 comment
When: User deletes that comment
Then: Run notification shall indicate 1 comment (audit trail record)
Test: REQ-NOTIF-005
Test: Verify label error counts per mix
Given: Run A with wells:
Well A1, Mix A, Error Type: Label Error
Well A2, Mix A, Error Type: Standard Error
Well A3, Mix B, Error Type: Label Error
Well A4, Mix B, Error Type: Label Error
Well A5, Mix B, Error Type: Standard Error
When: User expands Run A row in runfiles list
Then: Mix A sub-row shall show Label Errors: 1
And: Mix B sub-row shall show Label Errors: 2
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Architecture | Pusher (Real-Time Communication) |
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 non-normative 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
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- Refinements folded into Acceptance Criteria (section removed - was empty)
- Traceability matrix is complete
Reviewer Notes
No consolidations were performed during this conversion. The five source requirements represent distinct system capabilities:
| Source Requirement | Capability | Disposition |
|---|---|---|
| REQ-NOTIF-001 | Display status indicators | Preserved as FR-NOTIF-001 |
| REQ-NOTIF-002 | Interactive filtering | Preserved as FR-NOTIF-002 |
| REQ-NOTIF-003 | Special error category | Preserved as FR-NOTIF-003 |
| REQ-NOTIF-004 | Configurable comment counting | Preserved as FR-NOTIF-004 |
| REQ-NOTIF-005 | Mix-level error counts | Preserved as FR-NOTIF-005 |
Rationale: These requirements represent orthogonal capabilities: REQ-NOTIF-001 handles display, REQ-NOTIF-002 handles interaction, REQ-NOTIF-003 handles a specific error type, REQ-NOTIF-004 handles configuration, and REQ-NOTIF-005 handles granular detail display. They are not variants of a single capability.
Reversibility: Source file preserved at output/pilot/restructured/notif.md