Error Codes
Version: v3.1.0 Status: Normative (text), Illustrative (diagrams only) Scope: Generation, categorization, and assignment of error codes during analysis Domain: ERRORCODES
Statement
The system shall generate, categorize, and assign error codes during run file processing and analysis to indicate specific conditions detected by analytical rules, validation processes, or quality control checks.
Error codes are configurable database entities assigned at three levels (well, target, or mix). They fall into two categories: seed error codes (required by hardcoded rule implementations) and custom error codes (client-defined for Combined Outcomes and Error Resolutions). Error codes may be analytical (indicating QC violations) or blocking (preventing further processing until resolved).
Behavior Overview (Illustrative)
This diagram illustrates the error code lifecycle. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Seed Error Code | An error code that must exist in the configuration database because rule implementations are hardcoded to output it |
| Custom Error Code | An error code added by clients for use in Combined Outcomes or Error Resolutions |
| Error Resolution | A configured action that can be applied to resolve an error, potentially triggering re-analysis with rules skipped |
| Does Prevent Analyse | A per-error-code configuration flag that determines whether the error stops analysis flow |
| Westgard Rules | Statistical quality control rules (e.g., 1:2s, 1:3s, 7T) that detect out-of-control conditions in control samples |
| Control Sample | A sample with known expected behavior used for QC (positive control, negative control, extraction control) |
| Internal Control (IC) | A target added to samples to detect inhibition of the PCR reaction |
| CT (Cycle Threshold) | The PCR cycle number at which fluorescence exceeds a threshold, indicating target detection |
| Blocking Error | An error that prevents further processing until resolved |
| Well-level Error | An error code assigned to the entire well |
| Target-level Error | An error code assigned to a specific target within a well |
| Mix-level Error | An error code assigned to the entire mix |
| IC Mapping | A configuration that associates a control label with an internal control (IC) target for a mix |
Error Code Categories
By Origin
-
Seed error codes: Error codes that must exist in the configuration database because rule implementations are hardcoded to output them. These codes are required for the system to function correctly. Examples include Westgard violation codes (WG12S_HIGH_WELL), control check codes (FAILED_POS_WELL), and validation codes (UNKNOWN_MIX).
-
Custom error codes: Error codes added by clients for use in Combined Outcomes (REQ-KITCFG-011) and Error Resolutions (REQ-KITCFG-006). These are fully configurable and can be created, modified, or disabled through Kit Configuration.
By Assignment Level
- Well-level: Conditions affecting the entire well
- Target-level: Conditions affecting a specific target within a well
- Mix-level: Conditions affecting the entire mix
By Impact
- Analytical error codes: Generated during rule execution to indicate QC violations, control failures, or analytical anomalies. These may or may not prevent export depending on configuration.
- Blocking error codes: Generated during parsing or analysis validation that prevent further processing until resolved.
Product Context
The Error Codes domain interfaces with:
- Kit Configuration - Error Codes (error code entity management - REQ-KITCFG-005)
- Kit Configuration - Error Resolutions (resolution workflow - REQ-KITCFG-006)
- Kit Configuration - Combined Outcomes (custom error code usage - REQ-KITCFG-011)
- Rules Engine (error code output from rule execution - REQ-RULES-ENGINE-003)
- Run File Import (parsing validation)
- Well Analysis (analysis-stage validation)
- Run File Report (error code display)
- LIMS Export (error code inclusion in exports)
Functional Requirements
Westgard Statistical QC Error Codes (REQ-ERRORCODES-001)
FR-ERRORCODES-001 Generate Westgard Rule Error Codes
The system shall generate appropriate error codes when Westgard statistical quality control rules detect violations in control sample performance.
Acceptance Criteria:
General Behavior:
- Each Westgard rule violation shall produce error codes at both well and target levels
- Error codes shall indicate the direction of violation (HIGH or LOW)
- The system shall generate WESTGARDS_MISSED when Westgard limits are not configured for a mix
WG7T (7T Rule) Codes:
- WG7T_HIGH_WELL, WG7T_HIGH_TARGET
- WG7T_LOW_WELL, WG7T_LOW_TARGET
WG12S (1:2s Rule) Codes:
- WG12S_HIGH_WELL, WG12S_HIGH_TARGET
- WG12S_LOW_WELL, WG12S_LOW_TARGET
WG13S (1:3s Rule) Codes:
- WG13S_HIGH_WELL, WG13S_HIGH_TARGET
- WG13S_LOW_WELL, WG13S_LOW_TARGET
WG14S (1:4s Rule) Codes:
- WG14S_HIGH_WELL, WG14S_HIGH_TARGET
- WG14S_LOW_WELL, WG14S_LOW_TARGET
WG22S (2:2s Rule) Codes:
- WG22S_HIGH_WELL, WG22S_HIGH_TARGET
- WG22S_LOW_WELL, WG22S_LOW_TARGET
WG7T13S (Combined 7T+1:3s) Codes:
- WG7T13S_HIGH_WELL, WG7T13S_HIGH_TARGET
- WG7T13S_LOW_WELL, WG7T13S_LOW_TARGET
WG13S22S (Combined 1:3s+2:2s) Codes:
- WG22S13S_HIGH_WELL, WG22S13S_HIGH_TARGET
- WG22S13S_LOW_WELL, WG22S13S_LOW_TARGET
WGInError Codes:
- WG_IN_ERROR_WELL, WG_IN_ERROR_TARGET
Trace: Source: 3.0.0-Rules for Error Codes, 3.0.0-Error Codes Tab | Tests: See scenarios
Control Validation Error Codes (REQ-ERRORCODES-002)
FR-ERRORCODES-002 Generate Control Check Error Codes
The system shall generate appropriate error codes when control samples (positive controls, negative controls, extraction controls) fail their expected behavior validation.
Acceptance Criteria:
General Behavior:
- Positive control failures shall generate FAILED_POS codes at well and target levels
- Negative control failures shall generate NEC_FAILURE and NEGATIVE_FAILURE codes
- Out-of-range control values shall generate CONTROL_OUT_OF_RANGE codes with HIGH/LOW direction
- Cross-over control failures shall generate CROSS_CNTRL_FAIL codes at well and mix levels
- Missing controls shall generate CONTROL_MISSING or EXTRACTION_CONTROLS_MISSING codes
- Missing control limits shall generate CC_LIMITS_MISSED
BCC (Batch Control Check) Codes:
- FAILED_POS_WELL, FAILED_POS_TARGET
- CONTROL_OUT_OF_RANGE_HIGH_WELL, CONTROL_OUT_OF_RANGE_HIGH_TARGET
- CONTROL_OUT_OF_RANGE_LOW_WELL, CONTROL_OUT_OF_RANGE_LOW_TARGET
- CC_LIMITS_MISSED
BNC (Batch Negative Control) Codes:
- NEC_FAILURE_WELL, NEC_FAILURE_TARGET
- NEGATIVE_FAILURE_WELL, NEGATIVE_FAILURE_TARGET
BPEC (Batch Positive Extraction Control) Codes:
- FAILED_POS_WELL, FAILED_POS_TARGET
CONTROL_FAIL Codes:
- CROSS_CNTRL_FAIL_WELL
WCAF (Well Cross-over Assay Failure) Codes:
- CROSS_CNTRL_FAIL_WELL, CROSS_CNTRL_FAIL_MIX
MIN_CONTROLS Codes:
- CONTROL_MISSING
MINEXTRACT Codes:
- EXTRACTION_CONTROLS_MISSING
Trace: Source: 3.0.0-Rules for Error Codes, 3.0.0-Error Codes Tab | Tests: See scenarios
Inhibition Detection Error Codes (REQ-ERRORCODES-003)
FR-ERRORCODES-003 Generate Inhibition Error Codes
The system shall generate appropriate error codes when internal control (IC) analysis detects inhibition in samples or controls.
Acceptance Criteria:
General Behavior:
- Patient sample inhibition shall generate INH_WELL and IC_FAILED codes
- IC qualitative inhibition shall generate ICQUAL codes (RPT, FIRST_RUN, INHN variants)
- IC quantitative inhibition shall generate ICQUANT codes (INHN, INHP, FIRST_RUN variants)
- Serum-specific variants shall be generated for PICQUAL and PICQUANT rules
- Systemic inhibition detection shall generate SYSTEMIC_INHIBITION_DETECTED
- Batch IC qualitative failures shall generate BICQUAL codes
INH (Inhibition) Codes:
- INH_WELL, IC_FAILED
BICQUAL Codes:
- BICQUAL_WELL, BICQUAL_TARGET
BIC Codes:
- BICQUAL
PICQUAL Codes:
- ICQUAL_RPT, ICQUAL_FIRST_RUN
PICQUAL_SERUM Codes:
- ICQUAL_INHN
PICQUANT Codes:
- ICQUANT_INHN, ICQUANT_INHP, ICQUANT_FIRST_RUN
PICQUANT_SERUM Codes:
- ICQUANT_INHN, ICQUANT_INHP
SYSTEMIC_INHIBITION Codes:
- SYSTEMIC_INHIBITION_DETECTED
Trace: Source: 3.0.0-Rules for Error Codes, 3.0.0-Error Codes Tab | Tests: See scenarios
Quantification Error Codes (REQ-ERRORCODES-004)
FR-ERRORCODES-004 Generate Quantification Error Codes
The system shall generate appropriate error codes when quantitative analysis rules detect issues with CT values, standard curves, or quantification results.
Acceptance Criteria:
General Behavior:
- CT values above cutoff shall generate CT_ABOVE_CUTOFF
- Quantification limit violations shall generate RQUANT_LIMITS_MISSED
- Missing quantification standards shall generate QUANT_STANDARDS_MISSING
- Quantification validation failures shall generate specific codes for each failure type
- Unable-to-quantify conditions shall generate UNABLE_TO_QUANTIFY
- The RQUANTASQUAL rule shall produce outcomes only without generating specific error codes
RQUAL Codes:
- CT_ABOVE_CUTOFF
RQUANT Codes:
- RQUANT_LIMITS_MISSED
QSSC Codes:
- QUANT_STANDARDS_MISSING
QUANT_VALIDATION Codes:
- INSUFFICIENT_STANDARD_CONTROLS
- BAD_R2
- BAD_GRADIENT
- BAD_EFFICIENCY
- STANDARD_WITHOUT_QUANT
- STANDARD_OUTSIDE_CT_RANGE
STDQT Codes:
- UNABLE_TO_QUANTIFY
Trace: Source: 3.0.0-Rules for Error Codes, 3.0.0-Error Codes Tab | Tests: See scenarios
CT and Threshold Error Codes (REQ-ERRORCODES-005)
FR-ERRORCODES-005 Generate CT and Threshold Error Codes
The system shall generate appropriate error codes when CT (cycle threshold) analysis detects issues with values, adjustments, or threshold configurations.
Acceptance Criteria:
General Behavior:
- CT adjustment applied shall generate ADJ_CT code
- Missing adjustment limits shall generate ADJ_LIMITS_MISSED
- Threshold configuration issues shall generate THRESHOLD_WRONG or THRESHOLD_MISSED
- Indeterminate CT values shall generate INDETERMINATE_CTS
- CT delta violations shall generate BAD_CT_DELTA
- Zika-specific adjustments shall generate ZIKA_ADJ codes
- The ICCT rule shall produce outcomes only without generating specific error codes
ADJ (CT Adjustment) Codes:
- ADJ_CT, ADJ_LIMITS_MISSED
Adj_Zika Codes:
- ZIKA_ADJ_CT, ZIKA_ADJ_LIMITS_MISSED
THRESHOLD Codes:
- THRESHOLD_WRONG, THRESHOLD_MISSED
INDETERMINATE_CT Codes:
- INDETERMINATE_CTS
DELTA_CT Codes:
- BAD_CT_DELTA
Trace: Source: 3.0.0-Rules for Error Codes, 3.0.0-Error Codes Tab | Tests: See scenarios
Classification Discrepancy Error Codes (REQ-ERRORCODES-006)
FR-ERRORCODES-006 Generate Classification Discrepancy Error Codes
The system shall generate appropriate error codes when classification or discrepancy detection rules identify inconsistencies between expected and observed classifications.
Acceptance Criteria:
General Behavior:
- Well classification discrepancies shall generate CLSDISC_WELL
- Control classification discrepancies shall generate CONTROL_CLSDISC codes
- CT discrepancies shall generate CTDISC codes for wells and controls
- Final classification issues shall generate CUTOFF_LIMITS_MISSED
- Replication quality issues shall generate RQ_CLS and RQ_LOG
WDCLS (Well Discrepancy Classification) Codes:
- CLSDISC_WELL
WDCLSC (Well Discrepancy Classification Control) Codes:
- CONTROL_CLSDISC_WELL, CONTROL_CLSDISC_TARGET
WDCT (Well Discrepancy CT) Codes:
- CTDISC_WELL
WDCTC (Well Discrepancy CT Control) Codes:
- CONTROL_CTDISC_WELL, CONTROL_CTDISC_TARGET
WFINALCLS (Well Final Classification) Codes:
- CUTOFF_LIMITS_MISSED
WREP (Well Replication) Codes:
- RQ_CLS, RQ_LOG
Trace: Source: 3.0.0-Rules for Error Codes, 3.0.0-Error Codes Tab | Tests: See scenarios
Bacteremia Error Codes (REQ-ERRORCODES-007)
FR-ERRORCODES-007 Generate Bacteremia Error Codes
The system shall generate appropriate error codes when bacteremia-related rules detect issues with bacterial sample matching or bacterial load validation.
Acceptance Criteria:
General Behavior:
- Missing bacterial matches shall generate BACT_NO_MATCHING_SAMPLE
- Invalid bacterial matches shall generate PATIENT_MATCHES_INVALID_BACT
- Low bacterial load conditions shall generate LOW_BACT
- Low bacterial load with negative patients shall generate NEG_PATIENT_HAS_LOW_BACT codes
- Low bacterial load with quantitative patients shall generate QUANT_PATIENT_HAS_LOW_BACT codes
- Tissue and HTLV combination issues shall generate BACT_TISSUE_AND_HTLV
RBACT Codes:
- BACT_NO_MATCHING_SAMPLE
- BACT_TISSUE_AND_HTLV
- LOW_BACT
SBCHECK Codes:
- PATIENT_HAS_NO_BACT_MATCH
- PATIENT_MATCHES_INVALID_BACT
- NEG_PATIENT_HAS_LOW_BACT_SUSPECTED
- QUANT_PATIENT_HAS_LOW_BACT_SUSPECTED
- NEG_PATIENT_HAS_LOW_BACT_CONFIRMED
- QUANT_PATIENT_HAS_LOW_BACT_CONFIRMED
Trace: Source: 3.0.0-Rules for Error Codes, 3.0.0-Error Codes Tab | Tests: See scenarios
Fluorescence Error Codes (REQ-ERRORCODES-008)
FR-ERRORCODES-008 Generate Fluorescence Error Codes
The system shall generate appropriate error codes when fluorescence analysis rules detect unexpected, missing, or abnormal fluorescence signals.
Acceptance Criteria:
General Behavior:
- Unexpected fluorescence shall generate UNEXPECTED_FL
- Maximum fluorescence limit violations shall generate MAXIMUM_FLUORESCENCE_MISSED
- Low fluorescence conditions shall generate LOW_FLUORESCENCE codes
- Minimum fluorescence limit violations shall generate MINIMUM_FLUORESCENCE_MISSED
- Incorrect sigmoid curve shapes shall generate INCORRECT_SIGMOID
UNEXPECTED_FL Codes:
- UNEXPECTED_FL
- MAXIMUM_FLUORESCENCE_MISSED
MINIMUM_FL Codes:
- LOW_FLUORESCENCE_TARGET
- LOW_FLUORESCENCE_WELL
- MINIMUM_FLUORESCENCE_MISSED
SIGMOID Codes:
- INCORRECT_SIGMOID
Trace: Source: 3.0.0-Rules for Error Codes, 3.0.0-Error Codes Tab | Tests: See scenarios
Miscellaneous Analytical Error Codes (REQ-ERRORCODES-009)
FR-ERRORCODES-009 Generate Miscellaneous Analytical Error Codes
The system shall generate appropriate error codes for analytical rule conditions not covered by the main rule categories, including ambiguity, inconclusive results, inheritance, and specialized checks.
Acceptance Criteria:
General Behavior:
- Ambiguous wells shall generate AMB_WELL
- Inconclusive results shall generate INCONCLUSIVE_WELL
- Inherited failures shall generate INHERITED_CONTROL_FAILURE and INHERITED_EXTRACTION_FAILURE
- Manual baseline checks shall generate MANUAL_BASELINE_CHECK codes
- Invalid tissue weight shall generate INVALID_TISSUE_WEIGHT
- Combined mixes with missing wells shall generate COMBINED_MIXES_WELLS_MISSING
AMB (Ambiguous) Codes:
- AMB_WELL
INCONCLUSIVE Codes:
- INCONCLUSIVE_WELL
WT (Well Transfer/Inheritance) Codes:
- INHERITED_CONTROL_FAILURE
- INHERITED_EXTRACTION_FAILURE
MANUAL_BASELINE Codes:
- MANUAL_BASELINE_CHECK_WELL
- MANUAL_BASELINE_CHECK_TARGET
TISSUE_WEIGHT Codes:
- INVALID_TISSUE_WEIGHT
MISSING_MIXES Codes:
- COMBINED_MIXES_WELLS_MISSING
Outcome-Only Rules (No Error Codes):
- COMBINED_OUTCOME rule produces outcomes only
- LIMS_EXPORT rule produces outcomes only
- RRESOLUTION rule produces outcomes only
- RWAC rule produces outcomes only
- GAPDH_ENT rule produces outcomes only
Trace: Source: 3.0.0-Rules for Error Codes, 3.0.0-Error Codes Tab | Tests: See scenarios
Parsing Validation Blocking Error Codes (REQ-ERRORCODES-010)
FR-ERRORCODES-010 Generate Parsing Validation Blocking Error Codes
The system shall validate run file structure and metadata during the parsing stage and generate blocking error codes for invalid files that prevent further processing.
Acceptance Criteria:
Validation Checks:
- Files with mismatched passive/non-passive observation counts shall generate INVALID_PASSIVE_READINGS
- Files missing the configured thermocycler JSON field shall generate THERMOCYCLER_UNKNOWN
- Files with invalid run file names (when using file name import approach) shall generate INVALID_FILENAME
Blocking Behavior:
- Blocking errors shall prevent rule processing until resolved
- Blocking errors shall prevent history inclusion until resolved
- Blocking errors shall prevent export until resolved
Error Handling
- Parsing blocking error detected: The system shall prevent further processing and require correction before proceeding
Trace: Source: 3.0.0-Rules for Error Codes (Parsing stage validation) | Tests: See scenarios
Analysis Validation Blocking Error Codes (REQ-ERRORCODES-011)
FR-ERRORCODES-011 Generate Analysis Validation Blocking Error Codes
The system shall validate each well's data during the analysis stage against configured rules and reference data, generating blocking error codes for invalid wells that prevent processing.
Acceptance Criteria:
Sample Label Validation:
- Invalid sample label structure shall generate SAMPLE_LABEL_IS_BAD
- Sample label structure shall require format: |tag:value|
- Valid tag characters shall be: A, C, D, E, T, R, N, X, Y, W
- Valid value characters shall be: words, numbers, spaces, dashes (-), dots (.)
Reference Data Validation:
- Unknown mix references shall generate UNKNOWN_MIX
- Unknown testcode references shall generate UNKNOWN_TESTCODE
- Testcode-mix mismatches shall generate MIX_DIDNT_MATCH_TC
- Unknown role-to-target mappings shall generate UNKNOWN_ROLE
- Missing testcodes shall generate TESTCODE_MISSING
Extraction Validation:
- Invalid extraction dates (future or invalid) shall generate INVALID_EXTRACTION_DATE
- Missing extraction dates shall generate EXTRACTION_DATE_MISSING
- Unknown or missing extraction instruments shall generate EXTRACTION_INSTRUMENT_UNKNOWN_WELL or EXTRACTION_INSTRUMENT_MISSING
- Missing or invalid extraction batch numbers shall generate EXTRACTION_BATCH_MISSING or INVALID_EXTRACTION_BATCH
Control and Accession Validation:
- Controls with accessions shall generate CNTRL_HAS_ACS
- Missing or invalid accessions shall generate ACCESSION_MISSING or INVALID_ACCESSION
Statistical Validation:
- Invalid standard deviation (for Westgard rules) shall generate INVALID_SD
Blocking Behavior:
- Blocking errors shall prevent rule processing, history inclusion, and export until resolved
Error Handling
- Analysis blocking error detected: The system shall prevent further processing of the affected well until correction
Trace: Source: 3.0.0-Rules for Error Codes (Analyzing stage validation) | Tests: See scenarios
IC Mapping Error Code (REQ-ERRORCODES-012)
FR-ERRORCODES-012 IC_MAPPED_BUT_NO_IC_TARGET Error Code Availability
The system shall provide a site-scoped error code IC_MAPPED_BUT_NO_IC_TARGET that is available for all sites and included in the Error Codes sheet export.
Acceptance Criteria:
Error Code Properties:
- The error code shall have level=Well, type=Error, and does_prevent_analyse=true
- The error code shall include a descriptive message indicating that an IC mapping exists but no IC target observation was found
- The error code shall be available for every site (inserted via migration for any site missing it)
Export Behavior:
- The error code shall appear as a row in the Error Codes configuration sheet export with the configured message and flags
Trace: Source: 3.1.0-Confluence Updates (Error Codes section), BT-4820 | Tests: See scenarios
IC Mapping Missing Observation Error (REQ-ERRORCODES-013)
FR-ERRORCODES-013 Raise IC_MAPPED_BUT_NO_IC_TARGET on Missing IC Target Observation
The system shall raise the IC_MAPPED_BUT_NO_IC_TARGET error code when a well has an IC mapping but no IC target observation exists for that mix.
Acceptance Criteria:
Detection Logic:
- When a control label is mapped as IC for a mix but the imported run does not contain an IC target observation for that mix, the system shall assign the IC_MAPPED_BUT_NO_IC_TARGET error code to the well
- The BicqualRule shall check for the missing IC target observation before performing further IC inhibition checks
Downstream Effects:
- When IC_MAPPED_BUT_NO_IC_TARGET is assigned, NEG_IC control rule mappings shall not be applied to the affected well
- The error shall appear in downstream exports and views that surface error codes
Trace: Source: 3.1.0-Confluence Updates (Error Codes section, BICQUAL Rule section), BT-4820, BT-6126 | Tests: See scenarios
Resolution Integration
Error codes integrate with the Error Resolution system (REQ-KITCFG-006) to enable user-driven resolution of QC errors.
Resolution Workflow (Illustrative)
This diagram illustrates the resolution workflow. It does not specify UI layout, styling, or interaction details.
Resolution Configuration Properties
| Property | Description |
|---|---|
| Resolution Message | Text describing the resolution action |
| Affected Wells | Which wells receive the resolution (by LIMS status, error code, or "All Wells") |
| Rules Skipped | Rules to skip during re-analysis |
| Outcome on Resolution | LIMS status to apply after resolution |
| Resolution Level | Scope: Well, All Observations, or Discrepant Observations |
See REQ-KITCFG-006 for full resolution configuration requirements.
Configuration Options
Error code behavior is configured through Kit Configuration (REQ-KITCFG-005). Each error code entity has the following configurable properties:
| Property | Description | Affects |
|---|---|---|
| Code | Unique error code identifier | All requirements |
| Message | Human-readable error description | Run File Report display |
| Type | Error categorization | Reporting, filtering |
| Affects | Assignment level: well or target | Error assignment |
| LIMS Export | Whether included in LIMS export | REQ-ERRORCODES-010, REQ-ERRORCODES-011 |
| Control Error | Flag for control-related errors | REQ-ERRORCODES-002 |
| Westgard Error | Flag for Westgard-related errors | REQ-ERRORCODES-001 |
| Prevents Analysis | Whether error blocks further processing | All blocking error requirements |
| Ignored | Whether error is hidden from reports | Run File Report display |
| Causes Missing Mixes | Flag for mix-related errors | REQ-ERRORCODES-011 |
| Is Inhibited | Flag for inhibition-related errors | REQ-ERRORCODES-003 |
Assumptions
- All seed error codes listed in this document exist in the Error Codes configuration table before rule execution is attempted
- The Rules Engine is configured with appropriate analytical rules before processing
- Mix configurations include required limits and thresholds for rule execution
- Error codes follow the naming convention:
{CONDITION}_{LEVEL}or{CONDITION}_{DIRECTION}_{LEVEL}where LEVEL is WELL, TARGET, or MIX - Users have appropriate permissions to view error codes on wells
- Error code properties (message, type, LIMS export, prevents_analyse, etc.) are configured per REQ-KITCFG-005
UI Notes (Illustrative)
Error code display specifications are documented in:
- Run File Report Requirements (how error codes are displayed on wells)
- Kit Configuration Requirements (how error codes are configured - REQ-KITCFG-005)
Implementation (Illustrative)
| Component | Type | Path | Requirements |
|---|---|---|---|
| ErrorCode | Model | code/app/ErrorCode.php | All requirements |
| Well | Model | code/app/Well.php | All requirements |
| ErrorCodesRelation | Relation | Custom Eloquent relation | All requirements |
| ErrorCodesController | Controller | code/app/Http/Controllers/ | REQ-ERRORCODES-001 through REQ-ERRORCODES-011 |
| ResolutionCodesController | Controller | code/app/Http/Controllers/ | Resolution integration |
Frontend Components (Illustrative)
| Component | Path |
|---|---|
| Error Codes View | views/ErrorCodes.vue |
| Error Resolution View | views/ErrorResolution.vue |
| Error Codes Components | components/error-codes/ |
| Resolution Codes Components | components/resolution-codes/ |
| Resolveable Wells Mixin | mixins/resolution/HandleResolveableWells.js |
| Filter Error Codes Mixin | mixins/FilterErrorCodes.js |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-ERRORCODES-001 | Generate Westgard Rule Error Codes | Test | ErrorCode, Rules Engine | [Pending] | Draft |
| REQ-ERRORCODES-002 | Generate Control Check Error Codes | Test | ErrorCode, Rules Engine | [Pending] | Draft |
| REQ-ERRORCODES-003 | Generate Inhibition Error Codes | Test | ErrorCode, Rules Engine | [Pending] | Draft |
| REQ-ERRORCODES-004 | Generate Quantification Error Codes | Test | ErrorCode, Rules Engine | [Pending] | Draft |
| REQ-ERRORCODES-005 | Generate CT and Threshold Error Codes | Test | ErrorCode, Rules Engine | [Pending] | Draft |
| REQ-ERRORCODES-006 | Generate Classification Discrepancy Error Codes | Test | ErrorCode, Rules Engine | [Pending] | Draft |
| REQ-ERRORCODES-007 | Generate Bacteremia Error Codes | Test | ErrorCode, Rules Engine | [Pending] | Draft |
| REQ-ERRORCODES-008 | Generate Fluorescence Error Codes | Test | ErrorCode, Rules Engine | [Pending] | Draft |
| REQ-ERRORCODES-009 | Generate Miscellaneous Analytical Error Codes | Test | ErrorCode, Rules Engine | [Pending] | Draft |
| REQ-ERRORCODES-010 | Generate Parsing Validation Blocking Error Codes | Test | ErrorCode, Parser | [Pending] | Draft |
| REQ-ERRORCODES-011 | Generate Analysis Validation Blocking Error Codes | Test | ErrorCode, Analyzer | [Pending] | Draft |
| REQ-ERRORCODES-012 | IC_MAPPED_BUT_NO_IC_TARGET Error Code Availability | Test | ErrorCode, Migration | [Pending] | Draft |
| REQ-ERRORCODES-013 | Raise IC_MAPPED_BUT_NO_IC_TARGET on Missing IC Target Observation | Test | ErrorCode, BicqualRule | [Pending] | Draft |
Notes
- Seed codes vs custom codes: The error codes listed in this document are seed codes that must exist in configuration. Clients may add custom error codes for Combined Outcomes and Resolutions.
- Rule outputs are hardcoded: Rule implementations output specific error code identifiers. These codes must exist in the Error Codes configuration table for rules to function.
- Configurability: While rule outputs are hardcoded, error code properties (message, type, prevents_analyse, etc.) are fully configurable per REQ-KITCFG-005.
- Some rules produce outcomes only without generating specific error codes (e.g., RQUANTASQUAL, COMBINED_OUTCOME, LIMS_EXPORT, RRESOLUTION, RWAC, GAPDH_ENT, ICCT)
- Error codes follow a consistent naming convention:
{CONDITION}_{LEVEL}where level is WELL, TARGET, or MIX - HIGH/LOW suffixes indicate directional violations (e.g., above or below threshold)
- Blocking errors must be resolved before further processing can continue
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| - | No open questions at this time | - | - | - |
Acceptance Tests
Test: REQ-ERRORCODES-001
Test: Verify WG12S (1:2s) error codes
Given: A control sample with CT value more than 2 standard deviations above mean
When: The WG12S rule is executed
Then: WG12S_HIGH_WELL error code is assigned to the well
And: WG12S_HIGH_TARGET error code is assigned to the relevant target
Test: Verify WESTGARDS_MISSED when limits not configured
Given: A mix without Westgard limits configured
When: A control sample is processed
Then: WESTGARDS_MISSED error code is assigned
Test: REQ-ERRORCODES-002
Test: Verify positive control failure
Given: A positive control sample with unexpected negative result
When: The BCC rule is executed
Then: FAILED_POS_WELL error code is assigned to the well
And: FAILED_POS_TARGET error code is assigned to the relevant target
Test: Verify negative control failure
Given: A negative control sample with unexpected positive result
When: The BNC rule is executed
Then: NEC_FAILURE_WELL error code is assigned to the well
Test: REQ-ERRORCODES-003
Test: Verify patient inhibition detection
Given: A patient sample with internal control failure indicating inhibition
When: The INH rule is executed
Then: INH_WELL error code is assigned to the well
Test: REQ-ERRORCODES-004
Test: Verify CT above cutoff
Given: A sample with CT value above the configured cutoff
When: The RQUAL rule is executed
Then: CT_ABOVE_CUTOFF error code is assigned
Test: Verify quantification validation failure
Given: A run with standard curve R-squared value below threshold
When: The QUANT_VALIDATION rule is executed
Then: BAD_R2 error code is assigned to the mix
Test: REQ-ERRORCODES-005
Test: Verify CT adjustment
Given: A sample requiring CT adjustment per configured rules
When: The ADJ rule is executed
Then: ADJ_CT error code is assigned
Test: REQ-ERRORCODES-006
Test: Verify classification discrepancy
Given: A well with target classifications that disagree
When: The WDCLS rule is executed
Then: CLSDISC_WELL error code is assigned to the well
Test: REQ-ERRORCODES-007
Test: Verify bacterial match validation
Given: A patient sample requiring bacterial control matching
When: No matching bacterial control is found
Then: PATIENT_HAS_NO_BACT_MATCH error code is assigned
Test: REQ-ERRORCODES-008
Test: Verify unexpected fluorescence detection
Given: A sample with unexpected fluorescence signal in a channel
When: The UNEXPECTED_FL rule is executed
Then: UNEXPECTED_FL error code is assigned
Test: REQ-ERRORCODES-009
Test: Verify ambiguous well detection
Given: A well with ambiguous classification
When: The AMB rule is executed
Then: AMB_WELL error code is assigned
Test: REQ-ERRORCODES-010
Test: Verify passive readings validation
Given: A run file with mismatched passive observation count
When: The run file is parsed
Then: INVALID_PASSIVE_READINGS error is generated
And: The file cannot be processed further until corrected
Test: Verify thermocycler validation
Given: A run file missing the thermocycler JSON field
When: The run file is parsed
Then: THERMOCYCLER_UNKNOWN error is generated
Test: REQ-ERRORCODES-011
Test: Verify sample label validation
Given: A well with label "Patient|A:123|B:456"
When: The well is analyzed
Then: The label is parsed successfully
Given: A well with label "Invalid!Label@Format"
When: The well is analyzed
Then: SAMPLE_LABEL_IS_BAD error is generated
And: The well is not processed further until corrected
Test: Verify mix validation
Given: A well referencing mix "NonExistentMix"
When: The well is analyzed
Then: UNKNOWN_MIX error is generated
Test: Verify extraction date validation
Given: A well with extraction date in the future
When: The well is analyzed
Then: INVALID_EXTRACTION_DATE error is generated
Test: REQ-ERRORCODES-012
Test: Verify IC_MAPPED_BUT_NO_IC_TARGET error code exists for site
Given: A site with the v3.1.0 migration applied
When: The Error Codes configuration is queried
Then: IC_MAPPED_BUT_NO_IC_TARGET error code exists with level=Well, type=Error, and does_prevent_analyse=true
Test: Verify IC_MAPPED_BUT_NO_IC_TARGET appears in Error Codes sheet export
Given: A site with the IC_MAPPED_BUT_NO_IC_TARGET error code configured
When: The Error Codes sheet is exported
Then: A row for IC_MAPPED_BUT_NO_IC_TARGET exists with the configured message and flags
Test: REQ-ERRORCODES-013
Test: Verify IC_MAPPED_BUT_NO_IC_TARGET raised on missing IC target observation
Given: A control label is mapped as IC for a mix but a run is imported without an IC target observation for that mix
When: The run is analyzed
Then: The well receives error code IC_MAPPED_BUT_NO_IC_TARGET
And: NEG_IC control mappings are not applied to the affected well
And: The error appears in downstream exports and views that surface error codes
Related Requirements Documents
| Document | Relevant Sections |
|---|---|
| Kit Configuration | REQ-KITCFG-005 (Error Code Management), REQ-KITCFG-006 (Error Resolutions), REQ-KITCFG-011 (Combined Outcomes) |
| Rules Engine Framework | REQ-RULES-ENGINE-003 (Error/Warning Flow Control) |
| Configuration Import/Export | REQ-CONFIGIO-006 (Import/Export Error Codes Configuration) |
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Error Code Generation and Blocking Logic, Error Code Architecture |
| SDD Configuration | Error Codes Configurations, Error Resolutions Configurations |
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
- Refinements folded into Acceptance Criteria
- Traceability matrix is complete
Reviewer Notes
No Consolidation Required
The original 11 requirements in this domain were evaluated for consolidation but retained as separate requirements because:
| Original Requirement | Disposition | Rationale |
|---|---|---|
| REQ-ERRORCODES-001 (Westgard) | Retained | Distinct analytical domain - statistical QC |
| REQ-ERRORCODES-002 (Controls) | Retained | Distinct analytical domain - control validation |
| REQ-ERRORCODES-003 (Inhibition) | Retained | Distinct analytical domain - IC analysis |
| REQ-ERRORCODES-004 (Quantification) | Retained | Distinct analytical domain - quantitative analysis |
| REQ-ERRORCODES-005 (CT/Threshold) | Retained | Distinct analytical domain - cycle threshold |
| REQ-ERRORCODES-006 (Classification) | Retained | Distinct analytical domain - discrepancy detection |
| REQ-ERRORCODES-007 (Bacteremia) | Retained | Distinct analytical domain - bacterial analysis |
| REQ-ERRORCODES-008 (Fluorescence) | Retained | Distinct analytical domain - signal analysis |
| REQ-ERRORCODES-009 (Miscellaneous) | Retained | Catch-all for other analytical conditions |
| REQ-ERRORCODES-010 (Parsing) | Retained | Distinct processing stage - file parsing |
| REQ-ERRORCODES-011 (Analysis) | Retained | Distinct processing stage - well analysis |
Rationale: While all requirements follow the pattern "generate error codes when X condition occurs", each requirement represents a fundamentally different analytical domain or processing stage. They cannot be meaningfully consolidated into a single capability-level requirement without losing the distinct categorization that enables rule configuration and error code management.
Reversibility: Source file preserved at output/srs/errorcodes.md
Architectural Clarification (2026-01-18)
The Overview was expanded to clarify the error code architecture:
-
Seed vs Custom distinction: Error codes listed in this document are "seed codes" - they must exist in configuration because rule implementations are hardcoded to output them. Clients may add "custom codes" for Combined Outcomes and Resolutions.
-
Lifecycle documentation: Added diagram showing error code flow: Configuration -> Generation -> Display/Export -> Resolution.
-
Resolution integration: Added section documenting how error codes integrate with Error Resolutions (REQ-KITCFG-006) including re-analysis workflow with rules skipped.
-
Configuration properties: Documented the configurable properties of error code entities per REQ-KITCFG-005.
-
Cross-references: Added links to related requirements (
kitcfg.md,rules.md,configio.md) and design documents (sdd-algorithms.md,sdd-configuration.md).
This clarification resolves GAP-043 (SRS errorcodes.md improvement needed) which was blocking GAP-029 (SDD error codes section).
v3.1.0: Added IC_MAPPED_BUT_NO_IC_TARGET error code
Added two new requirements (REQ-ERRORCODES-012, REQ-ERRORCODES-013) for the IC_MAPPED_BUT_NO_IC_TARGET error code introduced in v3.1.0 (BT-4820, BT-6126):
-
REQ-ERRORCODES-012: Error code availability -- site-scoped, well-level, prevents analysis, inserted via migration, included in Error Codes sheet export.
-
REQ-ERRORCODES-013: Error code generation -- BicqualRule detects missing IC target observation when a control label is IC-mapped, assigns the error to the well, and prevents NEG_IC control rule mappings.
Source: 3.1.0-Confluence Updates (Error Codes section, BICQUAL Rule section)