Analyzer
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Data processing and validation of imported run files Domain: ANALYZER
Statement
The system shall support configurable validation of patient well data during run file import, allowing laboratories to control data quality enforcement rules.
This domain enables administrators to configure which special characters are permitted in accession identifiers during import. When allowed characters are configured, patient wells with accessions containing those characters pass validation; when no special characters are configured, only alphanumeric accessions are accepted. This provides flexibility for laboratories with varying data quality requirements.
Behavior Overview (Illustrative)
This diagram illustrates the high-level accession validation behavior. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Accession | A unique identifier assigned to a patient sample for tracking purposes |
| Patient Well | A well in a PCR plate that contains patient sample data (as opposed to control wells) |
| Validation Error | A flagged condition indicating that imported data does not meet configured quality rules |
Functional Requirements
Data Validation (REQ-ANALYZER-001)
FR-ANALYZER-001 Configure Accession Validation Enforcement
The system shall support configurable accession character validation during patient well import, allowing laboratories to control which special characters are permitted in accession identifiers.
Acceptance Criteria:
Validation Behavior:
- When allowed characters are configured, the system shall accept accessions containing alphanumeric characters plus the configured special characters, and flag accession errors for characters not in the allowed set
- When no allowed characters are configured (empty), the system shall accept only alphanumeric accessions and flag accession errors for any special characters
Scope:
- The allowed characters setting shall apply to all patient wells during a single import operation
- The allowed characters setting shall apply only to patient wells; control wells shall follow separate validation logic
- Accession character validation shall not affect other validation rules (e.g., format, required fields)
Configuration:
- The allowed characters configuration shall be controlled at the client level
Error Handling
- Configuration setting not found or empty: The system shall default to alphanumeric-only validation (no special characters allowed)
Trace: Source: 3.0.0-Bypass Accession Validation (Row 1) | Epic: BT-5282 | Jira: BT-5290 | Tests: TC-ANALYZER-001, TC-ANALYZER-002
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
allowed_characters_in_accessions | [] (empty array) | Array of special character patterns permitted in accession identifiers. When empty, only alphanumeric accessions are accepted. When populated, alphanumeric plus the listed characters are accepted. | REQ-ANALYZER-001 |
Assumptions
- Users have appropriate role permissions to import run files
- Client configuration settings are established before import operations
- The system distinguishes between patient wells and control wells during import
[REVIEW REQUIRED: Assumptions inferred from context, not explicitly stated in source. Confirm accuracy with SME.]
UI Notes (Illustrative)
FR-ANALYZER-001 UI Specifications
- Configuration setting location: Client Configuration screen
- Setting label: "Allowed characters in accessions"
- Setting type: Multi-select (character patterns)
Implementation (Illustrative)
| Component | Type | Path | Requirements |
|---|---|---|---|
| PatientValidator | Validator | code/app/Analyzer/Validators/PatientValidator.php | REQ-ANALYZER-001 |
| HasValidAccession | Validation Rule | code/app/Analyzer/Validators/Rules/HasValidAccession.php | REQ-ANALYZER-001 |
| PatientWell | Class | code/app/Analyzer/PatientWell.php | REQ-ANALYZER-001 |
| Well | Abstract Class | code/app/Analyzer/Well.php | REQ-ANALYZER-001 |
| EloquentConfigurationRepository | Repository | code/app/Analyzer/EloquentConfigurationRepository.php | REQ-ANALYZER-001 |
Key Implementation Details:
PatientValidator.phpline 19: Accession validation rule applied to patient wellsHasValidAccession.phplines 24-41: Validates accession format against allowed characters- Validation controlled via client configuration
allowed_characters_in_accessionssetting EloquentConfigurationRepository.php: Provides access to client configuration settings
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-ANALYZER-001 | Configure Accession Validation Enforcement | Test | PatientValidator.php, HasValidAccession.php | TC-ANALYZER-001, TC-ANALYZER-002 | Draft |
Notes
- This requirement is related to the wildcard targets epic (BT-5282)
- Configurable accession character validation provides flexibility for laboratories with varying data quality requirements
- Wells imported with validation errors flagged can be reviewed and corrected through the normal error resolution workflow
Open Questions
| ID | Question | Resolution | Owner | Date Raised |
|---|---|---|---|---|
| OQ-01 | What constitutes an "invalid accession"? Is this based on format, uniqueness, or external system lookup? | Depends on file import setting. Label-based import: missing required tags. Metadata-based import: invalid characters. | - | Resolved |
| OQ-02 | When validation errors are flagged, can they be resolved post-import or must the well be re-imported? | Via well edit options (post-import resolution supported) | - | Resolved |
Acceptance Tests
Test: TC-ANALYZER-001
Test: Allowed characters configured permits matching accessions
Given: A well with an accession containing special characters (e.g., "-", "_")
And: Client configuration "allowed_characters_in_accessions" includes those characters
When: The well is imported
Then: The well shall be imported without an accession error
Test: TC-ANALYZER-002
Test: Empty allowed characters rejects special character accessions
Given: A well with an accession containing special characters
And: Client configuration "allowed_characters_in_accessions" is empty
When: The well is imported
Then: The well shall be imported with an accession error flagged
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Run Analysis, Data Validation and Analysis |
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
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- All constraints folded into acceptance criteria
- Traceability matrix is complete
Reviewer Notes
Conversion Summary:
The source document contains a single requirement (REQ-ANALYZER-001). This conversion applies the new SRS readability format without consolidation.
| Source Requirement | Capability | Disposition |
|---|---|---|
| REQ-ANALYZER-001 | Configurable accession character validation | Preserved as FR-ANALYZER-001 |
Enhancements Made:
- Added Statement section for quick understanding
- Added Mermaid flowchart illustrating validation decision logic
- Grouped acceptance criteria by concern (Validation Behavior, Scope, Configuration)
- Added blank lines before bullet lists for PDF rendering
- Moved tests to end with back-links to requirement
- Marked UI Notes and Implementation as
(Illustrative)
Reversibility: Original file preserved at output/srs/analyzer.md