Version: Next

Config Import/Export

Version: v3.1.0 Status: Normative (text), Illustrative (diagrams only) Scope: Bulk configuration management via XLSX spreadsheet import and export Domain: CONFIGIO

Statement

The system shall enable administrators to import and export configuration data using XLSX spreadsheet files, supporting bulk management, environment migration, backup, and customer documentation.

Configuration import/export covers 14+ distinct configuration types including mixes and targets, combined outcomes, control labels, error codes, rules, automatic rule mappings, target name suffixes, and more. Each import operation generates a status report showing which rows were imported or ignored with reasons, while exports produce files that can be round-tripped back into the system.

As of v3.1.0, several configuration entities support a "global/strict" pattern where rows labeled "Global" for mix/target/dye fields are non-strict (apply broadly across matching targets), and non-strict rows that become unmatched are marked strict rather than deleted.

Behavior Overview (Illustrative)

This diagram illustrates the high-level behavior. It does not specify UI layout, styling, or interaction details.

Definitions

Term	Definition
Alternative Configuration	Configuration data imported via spreadsheet as alternative to UI-based configuration
Import Status Report	Generated XLSX file showing success/failure status for each imported row
Precedence Normalization	Automatic reordering of rule precedence values to remove gaps and resolve duplicates
Round-trip	Import followed by export that preserves all data without loss
Global (Non-Strict) Row	A configuration row where mix/target/dye fields are set to "Global", meaning the setting applies broadly to all matching targets via a mapper
Strict Row	A configuration row tied to a specific mix/target/dye combination; does not auto-map to other targets
Global Mapper	The process that takes non-strict (global) configuration settings and creates corresponding strict records for each matching target
Orphan Marking	When a non-strict configuration row no longer matches any global mapping, it is marked strict rather than deleted

Functional Requirements

Import Status Reporting (REQ-CONFIGIO-001)

FR-CONFIGIO-001 Generate Import Status Reports

The system shall generate an import status report for each configuration sheet import operation, indicating which rows were successfully imported and which were ignored.

Acceptance Criteria:

Notification:

Upon import completion, the system shall display a notification with the sheet name, count of imported rows, and count of ignored rows

Report Generation:

The system shall provide a downloadable report with a Status column appended to the imported sheet
Each row's Status shall be set to "Imported" or "Ignored"
Ignored rows shall include the reason for rejection

Trace: Source: 3.0.0-Alternative Configuration Sheet Import (Rows 1-3) | Jira: BT-2861 | Tests: BT-3714

Customer Documentation Export (REQ-CONFIGIO-002)

FR-CONFIGIO-002 Export Customer-Friendly Configuration

The system shall allow users to export a human-readable version of kit configuration formatted for customer review and documentation purposes.

Acceptance Criteria:

File Generation:

The system shall generate an XLSX file containing customer-friendly configuration data
The exported file shall be named using the pattern customer-friendly-kit-configurations-<site_name>.xlsx

Trigger:

The export shall be triggerable via keyboard shortcut

Trace: Source: 3.0.0-Customer Friendly Kit Configuration Export (Rows 1-2) | Jira: BT-3939 | Tests: [Pending]

Mix and Targets Configuration (REQ-CONFIGIO-003)

FR-CONFIGIO-003 Import and Export Mixes and Targets Configuration

The system shall support import and export of Mixes and Targets configuration data, validating field constraints during import.

Acceptance Criteria:

Supported Columns:

Import/Export shall support columns: MINIMUM FLUORESCENCE, IS QUANTITATIVE, MINIMUM FLUORESCENCE TO BE POSITIVE, USE_PASSIVE_DYE, MAX CT FOR CLS DISCREPANCY, MAX CT FOR CT DISCREPANCY, PREPEND CYCLES, QUANTITATIVE, DISABLED, TARGET ORDER, CALIBRATION FILE PATH, CHECK CLS DISCREPANCY, EXPECTED THRESHOLD, EXPORT NAME, PREFERRED RESULT PROVIDER, CT DISCREPANCY DELTA, MAXIMUM FLUORESCENCE, ENABLED

Field Validation:

Import shall validate MINIMUM FLUORESCENCE against precision limits (16 integer places, 16 decimal places)
Import shall validate IS QUANTITATIVE as boolean (TRUE/FALSE)
Import shall validate Expected Threshold as whole number within configured range
Import shall validate MAX CT values as numeric between 1 and 100, allowing null
Import shall validate PREPEND CYCLES as non-negative integer
Import shall validate QUANTITATIVE as optional boolean; must be consistent across all targets in the same mix; defaults to false when empty
Import shall validate DISABLED as optional boolean; when true, the mix is disabled; defaults to false when empty
Import shall validate TARGET ORDER as optional integer; when provided for any target in a mix, must be provided for all targets in that mix; must be numeric
Import shall validate CALIBRATION FILE PATH as optional string; sets calibration timestamp when provided
Import shall validate CHECK CLS DISCREPANCY as optional boolean; defaults to true when empty
Import shall validate EXPECTED THRESHOLD as optional float greater than 0; maximum 1000 for passive targets, maximum 100000000 for non-passive targets
Import shall validate EXPORT NAME as optional string
Import shall validate PREFERRED RESULT PROVIDER as required string with allowed values "MACHINE" or "DXAI"
Import shall validate CT DISCREPANCY DELTA as optional float; threshold for CT discrepancy detection
Import shall validate MAXIMUM FLUORESCENCE as optional decimal (32 integer places, 10 decimal places)
Import shall validate ENABLED (is_enabled) as optional boolean; defaults to true when empty; when false, target is disabled

Cross-Field Dependencies:

Import shall reject target rows where CHECK CLS DISCREPANCY is TRUE but CALIBRATION FILE PATH is empty; a calibration file is required to perform CLS discrepancy checking
Import shall reject target rows where CT DISCREPANCY DELTA is non-empty but CALIBRATION FILE PATH is empty; a calibration file is required to perform CT discrepancy checking

Passive Target Rules:

Import shall enforce that each mix has at most one passive target
Import shall validate Expected Threshold for passive targets as greater than 0 and maximum 1000
Import shall validate Expected Threshold for non-passive targets as greater than 0 and maximum 100000000
When multiple targets have is_passive = true for same mix, the system shall reject all rows for that mix

Import/Export Behavior:

Invalid rows shall be rejected with appropriate error messages
Export shall include all configured values for supported columns

Error Handling:

MINIMUM FLUORESCENCE exceeds precision limits: The system shall reject the row and report "Value exceeds maximum precision"
IS QUANTITATIVE not TRUE/FALSE: The system shall reject the row and report invalid boolean value
Multiple passive targets for same mix: The system shall reject all rows for that mix with error "More than 1 passive target defined"
MAX CT outside valid range: The system shall reject the row and report "Value must be between 1 and 100"
PREPEND CYCLES negative or non-integer: The system shall reject the row and report validation error
QUANTITATIVE values inconsistent within mix: The system shall reject all rows for that mix with error "Multiple quantification settings"
QUANTITATIVE not valid boolean: The system shall reject the row and report "Invalid quantification"
TARGET ORDER partially filled: The system shall reject all rows for that mix with error "Must fill all orders or not fill at all"
TARGET ORDER non-numeric: The system shall reject the row and report "Order must be numeric"
EXPECTED THRESHOLD invalid for passive target (>1000 or <=0): The system shall reject the row and report "Expected threshold must be between 0 and 1000"
EXPECTED THRESHOLD invalid for non-passive target (>100000000 or <=0): The system shall reject the row and report "Expected threshold must be between 0 and 100000000"
PREFERRED RESULT PROVIDER not "MACHINE" or "DXAI": The system shall reject the row and report invalid result provider
CHECK CLS DISCREPANCY enabled without calibration file: The system shall reject the row and report "Bson is required to enable check cls discrepancy"
CT DISCREPANCY DELTA set without calibration file: The system shall reject the row and report "Bson is required to enable check ct discrepancy"

Trace: Source: 3.0.0-Minimum Fluorescence For Mixes and Targets Configuration Import/Export (Rows 1-3), 3.0.0-Config Import : Mixes and Targets sheet - Add Is Quantitative column (Row 1), 3.0.0-Mix and Target Import sheet - Validate expected threshold (Row 1), 3.0.0-Mixes / Targets Import - Consider Passive Dye (Rows 1-3), 3.0.0-Import/Export - 'Max CT for CLS/CT Discrepancy', 3.0.0-Import/Export - Cycle Counts for Targets, CONFIG_COVERAGE_FIXES.md Phase B2 | Code: app/Imports/Sheets/MixAndTargetsImportSheet.php, app/Models/Mix.php, app/Models/Target.php, MixDataExtractor.php, TargetDataExtractor.php, IsQuantitativeValidator.php, TargetOrderValidator.php, ExpectedThresholdValidator.php | Jira: BT-3552, BT-4367, BT-4604, BT-5368, BT-5227, BT-5308, BT-4829 | Tests: BT-3562, BT-4677

Combined Outcomes Configuration (REQ-CONFIGIO-004)

FR-CONFIGIO-004 Import and Export Combined Outcomes Configuration

The system shall support import and export of Combined Outcomes configuration with comprehensive validation to ensure data integrity and consistency.

Acceptance Criteria:

Supported Columns:

Import/Export shall support columns: MIX, TARGET, ROLE, OUTCOME TYPE, WELL ERROR OR LIMS CODE, TARGET ERROR CODE, TARGET TO HAVE ERROR, IC FAILED, PRIORITY, NAME, CLS DISCREPANCY REQUIRED, CT DISCREPANCY REQUIRED, ALLOW OTHER RUNS TO BE USED, IS REPEAT, MIXES MISSING, MIX LEVEL OUTCOME TYPE, MIX LEVEL WELL ERROR CODE/LIMS CODE, MIX MISSING, USE_LATEST_UPLOADED_WELL, REQUIRED HISTORY OUTCOMES, RESULT, MIN CT, MAX CT, MIN QUANTITY, MAX QUANTITY, SPECIMEN

Mix Result Level Columns:

Import shall validate ALLOW OTHER RUNS TO BE USED as optional boolean (default: false); when true, allows matching wells from previous runs for the same patient; cannot be enabled when CLS Discrepancy Required or CT Discrepancy Required is true
Import shall validate IS REPEAT as optional boolean (default: false); when true, requires a matching historical well with the same outcome
Import shall validate MIXES MISSING as optional boolean (default: false); when true, combined outcome applies when specified mixes are NOT present
Import shall validate MIX LEVEL OUTCOME TYPE as optional string ("Error" or "Lims"); required if MIX LEVEL WELL ERROR CODE/LIMS CODE is filled
Import shall validate MIX LEVEL WELL ERROR CODE/LIMS CODE as optional string; must exist in error codes (if type=Error) or LIMS statuses (if type=Lims)
Import shall validate MIX MISSING as optional boolean (default: false); when true, the specific mix should NOT be present; all rows for same outcome must have consistent values
Import shall validate USE_LATEST_UPLOADED_WELL as optional boolean (default: false); when true, prioritizes most recently uploaded well
Import shall validate REQUIRED HISTORY OUTCOMES as optional comma-separated string; each outcome must exist in error codes or LIMS statuses; only allowed when IS REPEAT or ALLOW OTHER RUNS TO BE USED is true

Target Result Level Columns:

Import shall validate RESULT as optional string; must be one of: "Pos", "Neg", "Any", "Classification / Discrepancy"
Import shall validate MIN CT as optional integer between 1-90; when both MIN CT and MAX CT are provided, MAX CT must be >= MIN CT
Import shall validate MAX CT as optional integer between 1-90; when both MIN CT and MAX CT are provided, MAX CT must be >= MIN CT
Import shall validate MIN QUANTITY as optional decimal > 0 and <= 9999999999999999999999.9999999999; when both MIN and MAX are provided, MAX must be >= MIN
Import shall validate MAX QUANTITY as optional decimal > 0 and <= 9999999999999999999999.9999999999; when both MIN and MAX are provided, MAX must be >= MIN
Import shall validate SPECIMEN as optional string; must exist in Specimens configuration when use_sample_type is enabled; must be empty when disabled; "Any" or blank applies to all specimens

Role Validation:

Import shall validate ROLE as required, existing in Roles configuration, and not Ignore-typed
Import shall enforce Sample-typed roles have empty TARGET ERROR CODE and TARGET TO HAVE ERROR fields

Outcome Type Validation:

Import shall validate OUTCOME TYPE as required, either "Error" or "Lims"
Import shall enforce Control-typed roles can only have "Error" outcome type

Code Validation:

Import shall validate WELL ERROR CODE / LIMS CODE exists in appropriate configuration
Import shall validate TARGET ERROR CODE is empty for Sample-typed roles, optional for Control-typed
Import shall validate TARGET TO HAVE ERROR belongs to the specified mix when provided

Priority and Discrepancy:

Import shall validate PRIORITY as numeric
Imported priorities shall merge with existing priorities, shifting existing rows to accommodate
Import shall validate discrepancy required fields as boolean or blank
The system shall disable multi-run combined outcome feature when discrepancy requirements are used
Import shall interpret blank discrepancy values as "Any" (no discrepancy requirement)

Round-trip:

Export shall include all configured combined outcomes with all properties
IC FAILED value shall be preserved during round-trip import/export

Error Handling:

ROLE is blank or missing: The system shall reject the row and report "ROLE is required"
ROLE does not exist: The system shall reject the row and report "ROLE not found in configuration"
OUTCOME TYPE invalid: The system shall reject the row and report "OUTCOME TYPE must be Error or Lims"
Unsupported outcome code: The system shall reject the row and report "Outcome code is not supported"
TARGET ERROR CODE provided for Sample role: The system shall reject the row and report "TARGET ERROR CODE must be empty for Sample roles"
PRIORITY non-numeric: The system shall reject the row and report "PRIORITY must be numeric"
ALLOW OTHER RUNS TO BE USED with discrepancy enabled: The system shall reject the row and report "'Use other runs' not allowed because CLS discrepancy or CT discrepancy is required"
ALLOW OTHER RUNS TO BE USED invalid boolean: The system shall reject the row and report "Invalid 'other runs to be used' value"
IS REPEAT invalid boolean: The system shall reject the row and report "Invalid is repeat"
MIXES MISSING invalid boolean: The system shall reject the row and report "Invalid mixes missing"
MIX MISSING invalid boolean: The system shall reject the row and report "Invalid mix missing"
MIX MISSING inconsistent across rows: The system shall reject the row and report "mix_missing values must be consistent"
MIX LEVEL OUTCOME TYPE without code: The system shall reject the row and report "mix level: well error code or lims code filled without selecting outcome type"
MIX LEVEL OUTCOME TYPE invalid: The system shall reject the row and report "mix level: invalid outcome type"
USE_LATEST_UPLOADED_WELL invalid boolean: The system shall reject the row and report "Invalid use recent run"
REQUIRED HISTORY OUTCOMES without repeat or other runs: The system shall reject the row and report "Previous well outcomes are not allowed"
REQUIRED HISTORY OUTCOMES invalid outcome: The system shall reject the row and report "previous well outcomes are invalid"
RESULT invalid value: The system shall reject the row and report "Result not found"
MIN CT not integer: The system shall reject the row and report "CT value is not integer"
MIN CT or MAX CT out of range: The system shall reject the row and report "CT is not in valid range"
MAX CT < MIN CT: The system shall reject the row and report "Max CT is not greater than to min CT"
MIN QUANTITY or MAX QUANTITY not numeric: The system shall reject the row and report "Quantity is not numeric"
MIN QUANTITY or MAX QUANTITY out of range: The system shall reject the row and report "Quantity is not in valid range"
MAX QUANTITY < MIN QUANTITY: The system shall reject the row and report "Max quantity is not greater than to min quantity"
SPECIMEN invalid when use_sample_type enabled: The system shall reject the row and report "Invalid specimen name"
SPECIMEN filled when use_sample_type disabled: The system shall reject the row and report "Specimen is filled when 'use sample type' config is disabled"

Trace: Source: 3.0.0-Combined Outcomes - Import / Export with Spread Sheet (Rows 1-17), CONFIG_COVERAGE_FIXES.md Phase B1, 3.0.0-Prevent Un Supported Outcomes (Row 1), 3.0.0-Client Configurations Combined Outcomes Import/Export - Add IC Fail Option, 3.0.0-Add Priority/Name - Import/Export, 3.0.0-Import/Export - CLS/CT Discrepancy Required | Code: app/Imports/Sheets/CombinedOutcomesImportSheet.php, app/Actions/OutcomeToLimsStatus/ImportSupport/Validate/Validators/*.php, app/OutcomeToLimsStatusMapping.php, app/OutcomeToLimsMappingMixResult.php, app/OutcomeToLimsMappingTargetResult.php, app/Exports/Config/CombinedOutcomesExport.php | Jira: BT-3584, BT-4231, BT-3876, BT-4318, BT-5226, BT-5308 | Tests: BT-4239, BT-3885, BT-5230

Control Labels Configuration (REQ-CONFIGIO-005)

FR-CONFIGIO-005 Import and Export Control Labels Configuration

The system shall support import and export of Control Labels configuration including backup mixes, wildcards, IC delta check exclusion, and resolution priority settings.

Acceptance Criteria:

Supported Columns:

Import/Export shall support columns: BACKUP MIXES, LABELS_IN_IMPORTED_RUNFILE, EXCLUDE FROM IC DELTA CHECK, RESOLUTION PRIORITY

Control Labels Export Columns:

ROLE: The role name associated with the control label mapping
ROLE TYPE: The type of the associated role; valid values are PC, NC, Sample, Ignore, Quantification, Quantification & PC, Crossover; derived from the Role entity and exported as read-only
MIX: The mix(es) associated with the control label; displays "Global" for non-strict mappings, "All mixes" when all mixes are selected, or pipe-separated mix names
IS EXTRACTED: Boolean (displayed as Y/N) indicating whether samples with this role require an extraction date; derived from the Role's has_extraction property and exported as read-only; when Y, wells must have an actual extraction date; when N, the system uses runfile creation date
BACKUP MIXES: Pipe-separated list of backup mix names for failover
LABELS IN IMPORTED RUNFILE: Pipe-separated list of role aliases (labels) that map to this role

Format Validation:

BACKUP MIXES shall be formatted as pipe-separated mix names
Import shall validate wildcard notation ("*") is not in the middle of role alias
Import shall validate EXCLUDE FROM IC DELTA CHECK as Yes/No/empty

Conditional Import:

RESOLUTION PRIORITY shall only be imported when client config "Use role priority for resolution" is enabled
Sample, Ignore, and Crossover role types shall not accept resolution priority

Export:

Export shall include all configured values for supported columns
ROLE TYPE and IS EXTRACTED are derived from Role entity and exported as read-only columns

Error Handling:

Wildcard "*" appears in middle of role alias: The system shall reject the row and report invalid wildcard format
Resolution priority on invalid role type: The system shall reject the row and report "Role type cannot have resolution priority"

Trace: Source: 3.0.0-Control Labels Import/Export - Add backup mixes, 3.0.0-Import - Validate Wildcards in Control Label, 3.0.0-Roles Import/Export sheet - Add EXCLUDE FROM IC DELTA CHECK column, 3.0.0-Roles Import/Export - add role priority for resolution, CONFIG_COVERAGE_FIXES.md Phase C3 | Code: app/Imports/Sheets/ControlLabelsImportSheet.php, app/Role.php, app/Exports/ControlLabelsExport.php | Jira: BT-3883, BT-3965, BT-5287, BT-4900 | Tests: BT-3913, BT-3985, BT-5303

Error Codes Configuration (REQ-CONFIGIO-006)

FR-CONFIGIO-006 Import and Export Error Codes Configuration

The system shall support import and export of Error Codes configuration including error type, inhibition status, and missing mixes flag.

Acceptance Criteria:

Supported Columns:

Import/Export shall support columns: ERROR CODE, ERROR TYPE, IS INHIBITED, CAUSES MISSING MIXES, DEFAULT LIMS EXPORT

Data Values:

ERROR TYPE shall support "Associate Control Error" type
IS INHIBITED and CAUSES MISSING MIXES shall be boolean values
DEFAULT LIMS EXPORT shall be an optional string matching an existing LIMS status code

Import/Export Behavior:

Import shall create or update error codes based on import data
Export shall include all error codes with configured properties

Error Handling:

Invalid DEFAULT LIMS EXPORT value (not matching any LIMS status code): The system shall reject the row and report "Default Lims Status does not match with any available Lims Statuses"

Assumptions:

User has Super Administrator role

Trace: Source: 3.0.0-Associate Error Type - Config Import / Export, 3.0.0-Error codes config import/export sheet - Add is inhibited column, 3.0.0-"Error codes" config import/export sheet - add Causes Missing Mixes column, CONFIG_COVERAGE_FIXES.md Phase B4 | Code: app/Imports/Sheets/ErrorCodesImportSheet.php, LimsStatusValidator.php | Jira: BT-3734, BT-4150, BT-4505 | Tests: BT-3835, BT-4164

Error Resolutions Configuration (REQ-CONFIGIO-007)

FR-CONFIGIO-007 Import and Export Error Resolutions Configuration

The system shall support import and export of Error Resolution configuration including resolution level settings.

Acceptance Criteria:

Supported Columns:

Import/Export shall support columns: RESOLUTION LEVEL, RESOLUTION NUMBER, DROPDOWN CODE, DROPDOWN MESSAGE, OTHER WELLS AFFECTED BY RESOLUTION, LIMS MESSAGE

Validation:

Import shall validate RESOLUTION LEVEL as one of: "Well", "All Observations", "Discrepant Observations"
Import shall validate RESOLUTION NUMBER as required integer referencing an existing resolution message number for the site
Import shall validate DROPDOWN CODE and DROPDOWN MESSAGE as paired values (both provided or both empty); creates/updates resolution dropdown entry; when multiple resolutions share the same resolution message number, these values populate the dropdown selector shown to users when resolving wells
Import shall validate OTHER WELLS AFFECTED BY RESOLUTION as optional comma-separated list of LIMS status codes or "ALL WELLS"
Import shall reject rows where OTHER WELLS AFFECTED BY RESOLUTION contains "ALL WELLS" combined with other values
Import shall validate LIMS MESSAGE as optional string specifying the custom LIMS export message; when set, this message overrides the standard LIMS status message in well outcome displays
Import shall prevent adding resolutions to non-resolvable errors (ONE_STANDARD_CONTROL, STANDARD_WITHOUT_QUANT)

Export:

Export shall include all configured error resolutions with columns: RESOLUTION LEVEL, RESOLUTION NUMBER, DROPDOWN CODE, DROPDOWN MESSAGE, OTHER WELLS AFFECTED BY RESOLUTION, LIMS MESSAGE

Error Handling:

Invalid RESOLUTION LEVEL value: The system shall reject the row and mark as "Ignored"
RESOLUTION NUMBER empty or no matching resolution message: The system shall reject the row and mark as "Ignored" with reason "Resolution number is not filled" or "No matching resolution message"
OTHER WELLS AFFECTED BY RESOLUTION contains "ALL WELLS" with other values: The system shall reject the row and mark as "Ignored" with reason "Can't have other lims along with all wells"
Resolution added to non-resolvable error: The system shall reject the row and report "Cannot add resolution to non-resolvable error"

Assumptions:

User has Super Administrator role

Trace: Source: 3.0.0-Resolution Code Configuration Import / Export - Resolution Level, 3.0.0-Prevent Adding Resolutions to Non Resolvable Errors, CONFIG_COVERAGE_FIXES.md Phase B3 | Code: app/Imports/Sheets/ErrorResolutionsImportSheet.php, app/ResolutionMessage.php, app/ResolutionDropdown.php, app/ResolutionCode.php, ResolutionNumberValidator.php, ResolutionCodeDataExtractor.php, AffectedLimsStatusValidator.php | Jira: BT-3817, BT-4845 | Tests: BT-3862, BT-4864

Help Items Configuration (REQ-CONFIGIO-008)

FR-CONFIGIO-008 Import and Export Help Items Configuration

The system shall support import and export of Help Items configuration including all help item properties.

Acceptance Criteria:

Supported Columns:

Import/Export shall support columns: ORDER, TITLE, DESCRIPTION, TAGS, VIDEO, PAGES AVAILABLE

Field Validation:

Import shall validate ORDER as required integer; must be unique within import; rows are sorted by order before processing
Import shall validate TITLE as required string (max 255 characters); used to match existing help items for update
Import shall validate DESCRIPTION as required string
Import shall validate TAGS as optional comma-separated string; empty/null results in empty tags array
Import shall validate VIDEO as optional string; when provided, must match an existing HelpVideo filename (without extension)
Import shall validate PAGES AVAILABLE as required comma-separated list of page names; all page names must exist in the system's page list (e.g., "Run Files, User Management, Audits")

Import Behavior:

Rows are sorted by ORDER before processing
Existing help items are matched by TITLE; if found, the item is updated; otherwise a new item is created
Invalid rows (missing required fields, invalid video reference, or invalid page names) are marked as "Help item: ignored"

Tags Format:

Multiple tags shall be comma-separated (e.g., "tag1, tag2, tag3")
Empty/null tags shall result in empty tags value
Export shall format tags as comma-separated values or blank cell

Error Handling:

ORDER is empty or null: The system shall reject the row and mark as "Help item: ignored"
ORDER is not unique within import: The system shall reject the duplicate row and mark as "Help item: ignored"
TITLE is empty or null: The system shall reject the row and mark as "Help item: ignored"
DESCRIPTION is empty or null: The system shall reject the row and mark as "Help item: ignored"
PAGES AVAILABLE is empty or null: The system shall reject the row and mark as "Help item: ignored"
PAGES AVAILABLE contains invalid page name: The system shall reject the row and mark as "Help item: ignored"
VIDEO references non-existent HelpVideo: The system shall reject the row and mark as "Help item: ignored"

Trace: Source: 3.0.0-Import - Help Items Sheet - Import Tags, 3.0.0-Export - Help Items Sheet - Include Tags in Table, CONFIG_COVERAGE_FIXES.md Phase C1 | Code: app/Imports/Sheets/HelpItemsImportSheet.php, app/HelpItemSaveRequest.php, app/HelpItem.php, app/Exports/HelpItemsExport.php | Jira: BT-3974 | Tests: [Pending]

Rules Configuration (REQ-CONFIGIO-009)

FR-CONFIGIO-009 Import and Export Rules Configuration

The system shall support import and export of Rules configuration including error well handling and automatic precedence normalization.

Acceptance Criteria:

Supported Columns:

Import/Export shall support columns: TITLE, PROGRAMMATIC RULE NAME, TYPE, RULE DESCRIPTION, PRECEDENCE, IS ALLOW ERROR WELLS
Import shall validate TITLE as required string
Import shall validate PROGRAMMATIC RULE NAME as required string; serves as unique identifier per site; used as lookup key with site_id to match or create rules
Import shall validate TYPE as required string; must be one of: Parse, Import, Reanalysis, General, Reporting, Observation, Control Check, Sample Result, Apply Controls, Sample Check
Import shall validate RULE DESCRIPTION as required text; human-readable description of the rule's purpose
Import shall validate PRECEDENCE as required integer; represents relative ordering within rule type
IS ALLOW ERROR WELLS null/empty values shall be treated as false
Non-boolean IS ALLOW ERROR WELLS values shall be treated as false

Precedence Normalization:

Import shall normalize precedence based on rule type and relative precedence
Rule type precedence order shall be: Observation(1), Control Check(2), Sample Result(3), Apply Controls(4), Sample Check(5), Parse/Import/Reanalysis/General/Reporting(6)
Relative precedences within type shall be normalized (gaps removed)
Duplicate precedences within type shall be resolved (later rows get higher precedence)
New imported rules shall take priority over existing rules at same precedence

Export:

Export shall include all rule properties with columns: TITLE, PROGRAMMATIC RULE NAME, TYPE, RULE DESCRIPTION, PRECEDENCE, IS ALLOW ERROR WELLS

Rules Mapping Sheet (Supported Columns):

Import/Export shall support columns: RUN ORDER, RULE, TYPE, RULE DESCRIPTION, RULE ID, SPECIMEN NAME, ROLE, MIX, TARGET, DYE
RULE DESCRIPTION is read-only on export (sourced from parent Rule record); not validated on Rules Mapping import
Import shall validate RULE ID as required string; must match an existing rule's programmatic_rule_name
Import shall validate DYE as required string when TARGET is not "global"; used together with MIX to identify the target for the rule mapping
Import shall validate ROLE as required string; must match an existing role's role_name
Import shall validate SPECIMEN NAME as required when use_sample_type is enabled and role is sample-typed; must match an existing specimen
TARGET value "global" indicates a global mapping (applies to all targets); when not "global", MIX and DYE are used to look up the specific target

Rules Mapping Sheet (Export):

Export shall include all rule mappings with columns: RUN ORDER, RULE, TYPE, RULE DESCRIPTION, RULE ID, SPECIMEN NAME, ROLE, MIX, TARGET, DYE

Error Handling:

Missing TITLE, PROGRAMMATIC RULE NAME, TYPE, or RULE DESCRIPTION: The system shall reject the row and mark as "Ignored"
RULE ID empty: The system shall reject the row with reason "Rule id is not filled"
RULE ID not matching any rule: The system shall reject the row with reason "No matching rule"
MIX provided without DYE (or vice versa): The system shall reject the row with reason "Invalid mix and dye combination"
MIX/DYE combination not matching any target: The system shall reject the row with reason "No matching target"
Target is passive and map_passive_observation_roles is disabled: The system shall reject the row with reason "Matching target is passive"
ROLE not matching any role: The system shall reject the row with appropriate error

Trace: Source: 3.0.0-Rules - Allow Error Wells - Import / Export, 3.0.0-Config Import - Rules - Normalize Precedence Order Based on Rule Type and Relative Precedence (Rows 1-5), CONFIG_COVERAGE_FIXES.md Phase C5, CONFIG_COVERAGE_FIXES.md Phase C6 | Code: app/Rule.php, app/Imports/Actions/ImportRulesAction.php, app/Exports/RuleExport.php, app/Exports/RulesMappingExport.php, RuleIdValidator.php, RuleMappingImportRowValidator.php, TargetValidator.php | Jira: BT-3519, BT-4035 | Tests: BT-3559, BT-4054

QIR Quantification Settings (REQ-CONFIGIO-010)

FR-CONFIGIO-010 Import and Export QIR Quantification Settings

The system shall support import and export of Calculate Quantification Settings configuration with comprehensive validation rules.

Acceptance Criteria:

Supported Columns:

Import/Export shall support columns: TARGET, SLOPE, INTERCEPT, MIN SLOPE, MAX SLOPE, MIN EFFICIENCY, MAX EFFICIENCY, MIN R2, MIN CONTROLS

Validation Rules:

Import shall validate TARGET as required and existing in target table
Import shall require SLOPE and INTERCEPT together (both or neither)
Import shall validate MIN/MAX SLOPE as null or decimal with min <= max
Import shall validate MIN/MAX EFFICIENCY as null or decimal with min <= max
Import shall validate MIN R2 as null or decimal between 0 and 1
Import shall validate MIN CONTROLS as null or integer >= 2

Export:

Export shall include all quantification settings with all properties

Error Handling:

TARGET not found: The system shall reject the row and report "Target not found"
SLOPE without INTERCEPT (or vice versa): The system shall reject the row and report "SLOPE and INTERCEPT must be provided together"
MIN R2 outside 0-1 range: The system shall reject the row and report "MIN R2 must be between 0 and 1"
MIN CONTROLS < 2: The system shall reject the row and report "MIN CONTROLS must be at least 2"
Min value greater than max value: The system shall reject the row and report "Minimum cannot exceed maximum"

Trace: Source: 3.0.0-Calculate Quantification Settings Export, 3.0.0-Calculated Quantification Settings - XLSX Validation | Jira: BT-3554, BT-4002 | Tests: BT-3567

Westgard Limits Configuration (REQ-CONFIGIO-011)

FR-CONFIGIO-011 Validate Westgard Limits on Import

The system shall validate Standard Deviation values when importing Westgard Limits configuration.

Acceptance Criteria:

Validation:

Import shall validate SD as a number greater than 0
Rows with SD = 0 shall be ignored
Rows with valid SD > 0 shall be imported
Import shall validate DYE as optional string; when TARGET is not "Global", DYE combined with MIX identifies the target; must match an existing dye name in the system
Import shall validate RANGE START DATE as required date (string format or Excel serial number); sets the effective date for the Westgard limit; converted to UTC using site timezone

Error Handling:

Invalid DYE (not matching any dye when TARGET is not "Global"): The system shall reject the row with appropriate error
Invalid RANGE START DATE (empty, null, or invalid format): The system shall reject the row and report "Invalid date format. Expected a valid date string or Excel serial number."

Trace: Source: 3.0.0-Westgard limits Import sheet - Validate SD, CONFIG_COVERAGE_FIXES.md Phase C7 | Code: app/Imports/Sheets/WestgardLimitsImportSheet.php, WestgardLimitDataExtractor.php, DateValidator.php, DateCaster.php | Jira: BT-4696 | Tests: [Pending]

Reporting Cut-offs Configuration (REQ-CONFIGIO-012)

FR-CONFIGIO-012 Import Quantitative/Qualitative Reporting Cut-offs

The system shall support import of Reporting Cut-offs configuration with validation based on sample type settings.

Acceptance Criteria:

Supported Columns:

Import shall support columns: MIX, TARGET, SPECIMEN TYPE, QUANT OR CT, GROUP, GROUP DESCRIPTION, UPPER BOUNDARY
Validate QUANT OR CT as required string; valid values: "Quant" or "Ct"
Validate GROUP as optional integer (1-9 for RQUANT, 1 for RQUAL/RQUANTASQUAL); defaults to 1
Validate GROUP DESCRIPTION as optional string; defaults to "LoD"
Validate UPPER BOUNDARY as required numeric value
Validate MIX as required string; must match existing mix name
Validate TARGET as required string; "Global" applies to all targets in mix; otherwise must match existing target within mix

When "use sample type" is ENABLED:

Rows with specimen type shall be saved with specimen association
Specimen must have test code mapping for the specified mix
Rows without specimen type shall be imported without specimen association

When "use sample type" is DISABLED:

Rows with specimen type shall be rejected
Rows without specimen type shall be imported normally

Error Handling:

Invalid QUANT OR CT (empty or invalid value): The system shall reject the row and report "Quant or Ct is not present" or "Invalid option"
Invalid MIX (not matching any mix): The system shall reject the row with appropriate error
Invalid TARGET (not matching any target when not "Global"): The system shall reject the row with appropriate error
Invalid specimen/mix mapping: The system shall reject the row and report "Specimen does not have mapping for given mix"
Specimen provided when disabled: The system shall reject the row and report "Specimen is filled when 'use sample type' config is disabled"

Trace: Source: 3.0.0-Quantitative Reportings Import - Validate for specimen (Rows 1-6), CONFIG_COVERAGE_FIXES.md Phase F3 | Jira: BT-4211 | Tests: BT-4293

LIMS Export Configuration (REQ-CONFIGIO-013)

FR-CONFIGIO-013 Import and Export LIMS Export Configuration

The system shall support import and export of LIMS Export configuration including inhibition and analysis prevention settings.

Acceptance Criteria:

Supported Columns:

Import/Export shall support columns: CODE, MESSAGE, TYPE, RESULT, DOES PREVENT ANALYSE, CAUSES MISSING MIXES, IS INHIBITED

Validation:

Import shall validate CODE as required string; must be unique per site
Import shall validate MESSAGE as required string
Import shall validate TYPE as required string; must be one of: "Warning", "Exclude", "Information"
Import shall validate RESULT as optional string; must be one of: "DETECTED", "NOT_DETECTED" when provided; null indicates no result classification
Import shall validate DOES PREVENT ANALYSE as optional boolean (YES/NO) via BooleanCaster (default: true)
Import shall validate CAUSES MISSING MIXES as optional boolean via BooleanCaster (default: false)
Import shall validate IS INHIBITED as optional boolean via BooleanCaster (default: true)

Error Handling:

Missing CODE, MESSAGE, or TYPE: Reject row with status "Lims status: ignored"
Invalid RESULT value: Reject row with status "Lims status: ignored"
Invalid boolean value: Reject row with status "Lims status: ignored"

Import/Export Behavior:

Import shall create or update LIMS export entries based on CODE (unique key per site)
Export shall include all LIMS export entries with configured properties

Trace: Source: 3.0.0-LIMS Export - Import/Export - add is inhibited/Causes Missing Mixes/Does Prevent Analyse columns, CONFIG_COVERAGE_FIXES.md Phase F4 | Jira: BT-4505, BT-4150, BT-4027 | Tests: BT-4164, BT-4042

Extraction Instruments Toggle (REQ-CONFIGIO-014)

FR-CONFIGIO-014 Apply Extraction Instruments Toggle on Import

The system shall conditionally import Westgard configuration rows based on the Use Extraction Instruments client configuration toggle.

Acceptance Criteria:

Toggle Behavior:

When Use Extraction Instruments is ON, Westgard rows without Extraction Instruments shall be ignored
When Use Extraction Instruments is OFF, Westgard rows with Extraction Instruments shall be ignored
Ignored rows shall show status "Ignored" in the import report

Trace: Source: 3.0.0-Alternative Configuration Sheet Import depending on the Use Extraction Instruments toggle condition (Rows 1-3) | Jira: BT-2984 | Tests: BT-3713

Global/Strict Configuration Import/Export Pattern (REQ-CONFIGIO-015)

FR-CONFIGIO-015 Import and Export Configuration Entities with Global/Strict Row Semantics

The system shall support a global/strict import/export pattern for configuration entities where rows with "Global" in mix, target, and dye fields represent non-strict settings that apply broadly, and non-strict rows that become unmatched are marked strict rather than deleted.

Acceptance Criteria:

Import Behavior:

Import shall treat rows with "Global" for mix, target, and dye fields as non-strict (global) settings that apply broadly to matching targets
Import shall create global mapping records for non-strict rows, enabling the mapper to auto-generate strict records for matching targets
Import shall validate that global rows contain valid configuration values for all other required fields

Export Behavior:

Export shall represent non-strict (global) configuration rows with "Global" for mix, target, and dye columns
Export shall represent strict configuration rows with the actual mix name, target name, and dye name from the target relation

Mapper Behavior:

After import or save, the system shall run a global mapper that creates non-strict records for each target matching the global mapping criteria
The mapper shall restrict mapping to targets in mixes that satisfy the entity-specific matching criteria (e.g., matching role alias for Curve Control Limits)

Orphan Handling:

Non-strict configuration rows that no longer match any current global mapping shall be marked strict rather than deleted
The system shall not delete orphaned rows; instead it shall update their strict flag so they become fixed target-specific settings

Applicable Entities:

Reporting Cut-offs: Global rows apply to all targets in a mix; mapper creates cut-off records per matching target; orphaned non-strict cut-offs are marked strict
Combined Outcomes: Global outcomes (is_strict=false) apply across all mixes and targets; a single "global" mix entry with a "global" target is created; export includes "Global" labels for non-strict rows
Cross Contamination Limits (Adjacents): Global rows use "Global" for mix/target/dye; mapper creates adjacent records for matching targets; orphaned non-strict adjacents are marked strict
Curve Control Limits: Global rows store role_id in global mapping data; mapper restricts to targets in mixes that have the mapping's role alias (control label); orphaned non-strict limits are marked strict

Trace: Source: 3.1.0-Reporting Cut-offs (Rows 1-2), 3.1.0-Combined Outcomes (Rows 5, 9-10), 3.1.0-Cross Contamination Limits (Rows 1-2), 3.1.0-Curve Control Limits (Rows 1-2, 5-6) | Jira: BT-4820 | Tests: [Pending]

Control Labels Enhanced Columns (REQ-CONFIGIO-016)

FR-CONFIGIO-016 Import and Export Control Labels with IC Verification, Verifiable Targets, and Associated Specimens

The system shall support importing and exporting three new columns on the Control Labels sheet: verify_ic_target_is_positive, verifiable_targets, and associated_specimens.

Acceptance Criteria:

New Columns:

Import/Export shall support column VERIFY_IC_TARGET_IS_POSITIVE as a boolean (TRUE/FALSE) indicating whether IC targets should be positively verified for this control label
Import/Export shall support column VERIFIABLE_TARGETS as a comma-separated list of target names that are verifiable for this control label
Import/Export shall support column ASSOCIATED_SPECIMENS as a comma-separated list of specimen names associated with this control label

Validation:

Import shall validate VERIFY_IC_TARGET_IS_POSITIVE as boolean; non-boolean values shall cause the row to be rejected with an error about invalid verify-IC option
Import shall validate VERIFIABLE_TARGETS against available targets for the mix when verify_ic_target_is_positive is TRUE; invalid or missing targets shall cause the row to be rejected
Import shall validate ASSOCIATED_SPECIMENS against the site's configured specimens by specimen_name; unknown specimen names shall cause the row to be rejected with an error naming the invalid specimens

Backward Compatibility:

When the new columns are left empty, import shall behave as before (no verification or associations applied)

Persistence:

Imported values shall be persisted to the control_labels record including verifiable_target_ids (JSON), verify_ic_target_is_positive, and associated_specimen_ids so that downstream features (rules, analytics) can use them
Export shall reflect the stored values in the new columns

Error Handling:

VERIFY_IC_TARGET_IS_POSITIVE contains non-boolean value (e.g., "maybe"): The system shall reject the row and report invalid verify-IC option
VERIFIABLE_TARGETS contains a target name not found for the mix: The system shall reject the row and report the invalid target names
ASSOCIATED_SPECIMENS contains an unknown specimen name: The system shall reject the row and report the invalid specimen names

Trace: Source: 3.1.0-Control Labels (Rows 1-4) | Jira: BT-4820, BT-5894 | Tests: [Pending]

Control Labels Re-import Behavior (REQ-CONFIGIO-017)

FR-CONFIGIO-017 Migrate Wells and Apply Full Global Mapping Matching on Control Label Re-import

The system shall ensure that re-importing Control Labels does not leave wells pointing at deleted control labels, and shall use full global mapping criteria when marking non-strict labels as strict.

Acceptance Criteria:

Well Migration:

On re-import, the system shall soft-delete existing strict control labels and their related global mappings (using delete rather than forceDelete)
After the import loop, the system shall migrate wells from deleted control labels to new control labels with the same role_alias and mix_id
After well migration, the system shall force-delete the old soft-deleted control labels
Wells that pointed at an old control label shall now point at the corresponding new control label

Global Mapping Matching:

When marking non-strict control labels as strict during re-import, the system shall use full global mapping criteria (including new fields such as mix, role, verify-IC, verifiable targets) rather than matching only on role_id and site
Only control labels matching the full global mapping shall be marked strict; unrelated control labels shall not be affected

Trace: Source: 3.1.0-Control Labels (Rows 5-6) | Jira: BT-3149, BT-4820 | Tests: [Pending]

Mix and Targets Quantification Scope Import/Export (REQ-CONFIGIO-018)

FR-CONFIGIO-018 Import and Export Quantification Scope and Method for Mixes and Targets

The system shall replace the legacy QUANTITATIVE column with QUANTIFICATION_SCOPE and QUANTIFICATION_METHOD columns on the Mix and Targets sheet, and support target-level use_automatic_baseline import/export.

Acceptance Criteria:

Quantification Scope:

Import shall support a QUANTIFICATION_SCOPE column per mix with valid values: "OFF", "ALL", or "BY_SPECIMEN"
Import shall normalize the value (lowercase, trimmed); invalid values shall fall back to "OFF"
Import shall validate that QUANTIFICATION_SCOPE is consistent across all rows for the same mix; conflicting values shall cause the rows to be rejected with error "Multiple quantification settings"
The legacy QUANTITATIVE column shall no longer be read on import

Quantification Method:

Import shall support a QUANTIFICATION_METHOD column mapped to the QuantificationMethods enum
Invalid or empty quantification method values shall be treated as null and shall not cause import failure

Target Automatic Baseline:

Import shall support USE_AUTOMATIC_BASELINE as a boolean per target row
Export shall include USE_AUTOMATIC_BASELINE column with TRUE/FALSE values per target

Export Changes:

Export shall replace the QUANTITATIVE column with QUANTIFICATION_SCOPE (default "OFF" when null) and QUANTIFICATION_METHOD columns
Export shall include USE_AUTOMATIC_BASELINE column for each target

Virtual Mix Target Linking:

After importing mixes and targets, the system shall update virtual targets (rows with base_mix) by matching base mix targets by dye and setting the virtual target's mix_target_id to point at the base target

Error Handling:

Conflicting QUANTIFICATION_SCOPE values within a mix: The system shall reject all rows for that mix and report "Multiple quantification settings"

Trace: Source: 3.1.0-Mix and Targets (Rows 1-6) | Jira: BT-5894, BT-4820 | Tests: [Pending]

Cross Contamination Limits Import Validation (REQ-CONFIGIO-019)

FR-CONFIGIO-019 Skip Downstream Validation on Upstream Error for Cross Contamination Import

The system shall skip contamination-value and potential-contaminating/contaminated validations when quant_or_ct validation has already failed for the row during Cross Contamination Limits sheet import.

Acceptance Criteria:

Error Cascade Prevention:

When a row has an invalid quant_or_ct value, the system shall reject the row with only the quant_or_ct error and shall not add redundant or cascading errors for contamination value fields
When a row has valid quant_or_ct but invalid contamination values, the system shall reject the row with the contamination value errors

Trace: Source: 3.1.0-Cross Contamination Limits (Row 1) | Jira: BT-4820 | Tests: [Pending]

Automatic Rule Mappings Export Sheet (REQ-CONFIGIO-020)

FR-CONFIGIO-020 Export Automatic Rule Mappings in Configuration Export

The system shall include an Automatic Rule Mappings sheet in the configuration export file, containing all auto-generated (non-custom) rule mappings.

Acceptance Criteria:

Export Content:

The export shall include a sheet listing all automatically generated rule-to-role-to-target mappings for the site
Each row shall include rule name, rule ID, role, mix, target, dye, and specimen (where applicable)
The sheet shall distinguish auto-mapped rules from custom mappings

Trace: Source: 3.1.0-Automatic Rule Mappings | Jira: BT-4820 | Tests: [Pending]

Target Name Suffix Import Sheet (REQ-CONFIGIO-021)

FR-CONFIGIO-021 Import Target Name Suffix to Specimen Mappings via Configuration Sheet

The system shall support importing Target Name Suffix to Specimen mappings from a configuration sheet, enabling bulk mapping of target name suffixes to specimen types.

Acceptance Criteria:

Import Behavior:

Import shall support a Target Name Suffix sheet with columns for target name suffix and specimen name
Import shall normalize suffixes to uppercase before storage
Import shall validate suffix uniqueness (case-insensitive) within the site
Import shall resolve specimen names against the site's configured specimens

Validation:

Duplicate suffixes (case-insensitive) shall be rejected with an appropriate error
Unknown specimen names shall be rejected with an error identifying the invalid specimen

Trace: Source: 3.1.0-Target Name Suffix to Specimen | Jira: BT-5894 | Tests: [Pending]

Config Import Progress Indicator (REQ-CONFIGIO-022)

FR-CONFIGIO-022 Display Import Progress Updates During Configuration Import

The system shall provide progress indicator updates during configuration import operations, informing the user of the current import stage.

Acceptance Criteria:

Progress Reporting:

The system shall update the user on import progress as each sheet is processed
Progress updates shall indicate which sheet is currently being imported

Trace: Source: 3.1.0-Config Import Progress | Jira: BT-4820 | Tests: [Pending]

Configuration Options

Option	Default	Description	Affects
use_extraction_instruments	false	Toggle for extraction instrument-based Westgard import behavior	REQ-CONFIGIO-014
use_role_priority_for_resolution	false	Enable resolution priority import for Control Labels	REQ-CONFIGIO-005
use_sample_type	false	Enable specimen type validation for Reporting Cut-offs and Specimens	REQ-CONFIGIO-012, REQ-CONFIGIO-016

Assumptions

SME confirmed 2026-01-20.

Users performing import/export have Administrator or Super Administrator role
Import files conform to expected XLSX format with required column headers
System has network connectivity to download generated reports
Mix-dependent configurations can be imported even without existing mixes (unknown mixes are created as disabled)

UI Notes (Illustrative)

FR-CONFIGIO-001 UI Specifications

Notification displayed on import completion with:
- Title: Name of sheet being imported
- Message: "Number of rows imported: X, Number of rows ignored: Y."
- Button: "Download Report" (email) or "Click to download report" (app)
Downloaded report includes "Status" column appended to sheet

FR-CONFIGIO-002 UI Specifications

Export button located on Kit configurations page
Tooltip text: "Export Customer-Friendly Configuration Sheets"
Keyboard shortcut: P
Export icon displayed on button

Implementation (Illustrative)

Component	Location	Description
Controller	`ConfigDataController`	Entry point for config upload endpoint, dispatches import job
Job	`ConfigDataImportJob`	Background job processing config imports asynchronously
Import Orchestrator	`ConfigDataImport`	Multi-sheet import handler with 25 sheet types
Import Result Export	`KitConfigurationImportResultExportAction`	Generates import status report notifications (REQ-CONFIGIO-001)
Customer Export	`CustomerFriendlyKitConfigurationsExportAction`	Customer-friendly configuration export (REQ-CONFIGIO-002)
Mix/Target Import	`MixAndTargetsImportSheet`	Mixes and targets import with validation (REQ-CONFIGIO-003)
Combined Outcomes Import	`CombinedOutcomesImportSheet`	Combined outcomes import with chunking (REQ-CONFIGIO-004)
Control Labels Import	`ControlLabelsImportSheet`	Control labels import with wildcard validation (REQ-CONFIGIO-005)
Control Labels Export	`ControlLabelsExportAction`	Control labels CSV export (REQ-CONFIGIO-005)
Error Codes Import	`ErrorCodesImportSheet`	Error codes import with type validation (REQ-CONFIGIO-006)
Error Resolutions Import	`ErrorResolutionsImportSheet`	Error resolutions import (REQ-CONFIGIO-007)
Help Items Import	`HelpItemsImportSheet`	Help items import with tags (REQ-CONFIGIO-008)
Rules Import	`RulesImportSheet`	Rules import (REQ-CONFIGIO-009)
Precedence Normalizer	`PrecedenceNormalizer`	Rule precedence normalization algorithm (REQ-CONFIGIO-009)
QIR Import	`CalculatedQuantificationSettingsImportSheet`	Quantification settings import with validation (REQ-CONFIGIO-010)
Westgard Import	`WestgardLimitsImportSheet`	Westgard limits import with SD validation (REQ-CONFIGIO-011, REQ-CONFIGIO-014)
Reportings Import	`QuantitativeReportingsImportSheet`	Reporting cut-offs import with specimen validation (REQ-CONFIGIO-012)
LIMS Status Import	`LimsStatusImportSheet`	LIMS export codes import (REQ-CONFIGIO-013)
Extraction Export	`ExtractionModelExportAction`	Extraction instruments export (REQ-CONFIGIO-014)
Kit Config Export	`KitConfigurationsExportAction`	Full kit configuration export (REQ-CONFIGIO-003-014)
Global Mapping	`GlobalMapping`	Global mapping record for non-strict configuration entities (REQ-CONFIGIO-015)
Reporting Mapper	`ReportingMapper`	Maps global reporting cut-offs to matching targets (REQ-CONFIGIO-015)
Adjacent Mapper	`AdjacentMapper`	Maps global cross contamination limits to matching targets (REQ-CONFIGIO-015)
Control Range Mapper	`ControlRangeSettingMapper`	Maps global curve control limits to matching targets (REQ-CONFIGIO-015)
Control Labels Validators	`VerifyIcTargetIsPositiveValidator`, `VerifiableTargetsValidator`, `AssociatedSpecimensValidator`	New column validation for Control Labels (REQ-CONFIGIO-016)
Well Migration	`migrateWellsAndForceDeleteSoftDeletedControlLabels()`	Control label well migration on re-import (REQ-CONFIGIO-017)
Mix Data Extractor	`MixDataExtractor`	Quantification scope normalization and method extraction (REQ-CONFIGIO-018)
Virtual Target Linker	`UpdatesVirtualTargetsWithBaseTargets`	Virtual mix target linking after import (REQ-CONFIGIO-018)
Adjacents Validator	`AdjacentsImportRowValidator`	Cross contamination import validation cascade (REQ-CONFIGIO-019)
Rule Mappings Export	`RulesMappingExport`	Automatic rule mappings export sheet (REQ-CONFIGIO-020)
Suffix Import	`TargetNameSuffixImportSheet`	Target name suffix to specimen import (REQ-CONFIGIO-021)

Traceability Matrix

Requirement	Title	Verification	Implementation	Test Cases	Status
REQ-CONFIGIO-001	Generate Import Status Reports	Test	KitConfigurationImportResultExportAction	BT-3714	Draft
REQ-CONFIGIO-002	Export Customer-Friendly Configuration	Test	CustomerFriendlyKitConfigurationsExportAction	[Pending]	Draft
REQ-CONFIGIO-003	Import and Export Mixes and Targets Configuration	Test	MixAndTargetsImportSheet, KitConfigurationsExportAction	BT-3562, BT-4677	Draft
REQ-CONFIGIO-004	Import and Export Combined Outcomes Configuration	Test	CombinedOutcomesImportSheet, KitConfigurationsExportAction	BT-4239, BT-3885, BT-5230	Draft
REQ-CONFIGIO-005	Import and Export Control Labels Configuration	Test	ControlLabelsImportSheet, ControlLabelsExportAction	BT-3913, BT-3985, BT-5303	Draft
REQ-CONFIGIO-006	Import and Export Error Codes Configuration	Test	ErrorCodesImportSheet, KitConfigurationsExportAction	BT-3835, BT-4164	Draft
REQ-CONFIGIO-007	Import and Export Error Resolutions Configuration	Test	ErrorResolutionsImportSheet, KitConfigurationsExportAction	BT-3862, BT-4864	Draft
REQ-CONFIGIO-008	Import and Export Help Items Tags	Test	HelpItemsImportSheet, KitConfigurationsExportAction	[Pending]	Draft
REQ-CONFIGIO-009	Import and Export Rules Configuration	Test	RulesImportSheet, PrecedenceNormalizer	BT-3559, BT-4054	Draft
REQ-CONFIGIO-010	Import and Export QIR Quantification Settings	Test	CalculatedQuantificationSettingsImportSheet	BT-3567	Draft
REQ-CONFIGIO-011	Validate Westgard Limits on Import	Test	WestgardLimitsImportSheet	[Pending]	Draft
REQ-CONFIGIO-012	Import Quantitative/Qualitative Reporting Cut-offs	Test	QuantitativeReportingsImportSheet	BT-4293	Draft
REQ-CONFIGIO-013	Import and Export LIMS Export Configuration	Test	LimsStatusImportSheet, KitConfigurationsExportAction	BT-4164, BT-4042	Draft
REQ-CONFIGIO-014	Apply Extraction Instruments Toggle on Import	Test	WestgardLimitsImportSheet, ExtractionModelExportAction	BT-3713	Draft
REQ-CONFIGIO-015	Global/Strict Configuration Import/Export Pattern	Test	GlobalMapping, ReportingMapper, AdjacentMapper, ControlRangeSettingMapper	[Pending]	Draft
REQ-CONFIGIO-016	Control Labels Enhanced Columns	Test	ControlLabelsImportSheet, VerifyIcTargetIsPositiveValidator	[Pending]	Draft
REQ-CONFIGIO-017	Control Labels Re-import Behavior	Test	ControlLabelsImportSheet	[Pending]	Draft
REQ-CONFIGIO-018	Mix and Targets Quantification Scope Import/Export	Test	MixDataExtractor, MixAndTargetsImportAction, MixExport	[Pending]	Draft
REQ-CONFIGIO-019	Cross Contamination Limits Import Validation	Test	AdjacentsImportRowValidator	[Pending]	Draft
REQ-CONFIGIO-020	Automatic Rule Mappings Export Sheet	Test	RulesMappingExport	[Pending]	Draft
REQ-CONFIGIO-021	Target Name Suffix Import Sheet	Test	TargetNameSuffixImportSheet	[Pending]	Draft
REQ-CONFIGIO-022	Config Import Progress Indicator	Test	ConfigDataImportJob	[Pending]	Draft

Notes

Import status report format is XLSX
Ignored rows in status report include reason for rejection
Toggle settings (Use Extraction Instruments, Use role priority for resolution, Use sample type) are set in Client Configurations

Acceptance Tests

Test: REQ-CONFIGIO-001

Back to requirement

Test: Verify import notification

Given: User navigates to Kit Configurations page
When: User imports a configuration sheet
Then: The system shall display a notification with title, message showing "Number of rows imported: X, Number of rows ignored: Y", and download report option

Test: Verify status column in report

Given: User has imported a configuration sheet
When: User downloads the status report
Then: The downloaded XLSX file shall contain a "Status" column with values "Imported" or "Ignored" for each row

Test: REQ-CONFIGIO-002

Back to requirement

Test: Export generates correct file

Given: User on Kit Configurations page
When: User triggers customer-friendly export
Then: The system shall download file with filename customer-friendly-kit-configurations-<site_name>.xlsx

Test: Export via keyboard shortcut

Given: User on Kit Configurations page
When: User presses P key
Then: The system shall export customer-friendly configuration sheets

Test: REQ-CONFIGIO-003

Back to requirement

Test: Minimum Fluorescence import succeeds

Given: Mix and target sheet with Target A, Minimum Fluorescence: 100000
When: User imports the sheet
Then: Target A shall have minimum fluorescence: 100000

Test: Minimum Fluorescence validation rejects invalid precision

Given: Mix and target sheet with Minimum Fluorescence value exceeding 16 decimal places
When: User imports the sheet
Then: The row shall not be imported
And: Status shall be "Ignored" with appropriate error message

Test: Is Quantitative import

Given: Row with Mix: HDV, Is Quantitative: FALSE and Row with Mix: ABVQ, Is Quantitative: TRUE
When: User imports mixes
Then: HDV shall have Is Quantitative false
And: ABVQ shall have Is Quantitative true

Test: Passive target validation rejects multiple passive targets

Given: Mix row with 3 target rows, more than 1 target has is_passive: true
When: User imports sheet
Then: All rows for that mix shall not be imported
And: Error message shall indicate more than 1 passive target

Test: Max CT for CLS Discrepancy import

Given: Mixes rows with Mix A Target A max ct: null, Mix A Target B max ct: 30
When: User imports config
Then: Target A max ct shall be null
And: Target B max ct shall be 30

Test: Max CT validation rejects out-of-range values

Given: Mix target row with max ct < 1 or max ct > 100
When: User imports config
Then: Mix target shall not be imported

Test: REQ-CONFIGIO-004

Back to requirement

Test: Combined Outcomes import with validation

Given: Combined outcome sheet with valid ROLE, OUTCOME TYPE, WELL ERROR CODE
When: User imports the config sheet
Then: Combined outcome shall be saved with all properties

Test: ROLE validation rejects blank

Given: Combined outcome sheet with ROLE column blank
When: User imports config sheet
Then: Row shall not be imported

Test: OUTCOME TYPE validation rejects invalid

Given: Combined outcome sheet with OUTCOME TYPE: "invalid_value"
When: User imports config sheet
Then: Row shall not be imported

Test: REQ-CONFIGIO-005

Back to requirement

Test: Wildcard validation

Given: Control Label sheet with labels_in_imported_runfile: "POS* | *SARS-CoV-2 PC" (valid) and "NTC* | Ne*g" (invalid)
When: User imports control labels sheet
Then: First row shall be imported
And: Second row shall be ignored with wildcard error message

Test: Resolution Priority import

Given: Client config Use role priority for resolution: true
And: Roles with resolution priority values
When: User imports kit configuration
Then: Roles shall have resolution priority values preserved

Test: REQ-CONFIGIO-009

Back to requirement

Test: Precedence normalization

Given: Rules config sheet with rule 1 type Observation precedence 1, rule 2 type Observation precedence 2, rule 3 type Control check precedence 1
When: User imports rule config
Then: Rules shall have global precedence: rule 1 = 1, rule 2 = 2, rule 3 = 3

Test: Normalize duplicate precedences

Given: Rules config with two rules having same precedence within type
When: User imports rule config
Then: Precedences shall be normalized to sequential values

Test: REQ-CONFIGIO-010

Back to requirement

Test: Slope and Intercept together required

Given: Quantification Settings sheet with slope: 1.5, intercept: null
When: User imports file
Then: Record shall not be present in QIR table

Given: Quantification Settings sheet with slope: 1.5, intercept: 2.4
When: User imports file
Then: Record shall be present in QIR table

Test: Min R2 validation

Given: Sheet with min_r2: -0.125 or min_r2: 2.5
When: User imports file
Then: Record shall not be imported

Given: Sheet with min_r2: 0.125
When: User imports file
Then: Record shall be imported

Test: REQ-CONFIGIO-012

Back to requirement

Test: Specimen validation when enabled

Given: Use sample type enabled
And: Reporting rows with valid and invalid specimen/mix mappings
When: User imports Config sheet
Then: Valid mapping rows shall be imported
And: Invalid mapping rows shall be ignored with error message

Test: Specimen rejection when disabled

Given: Use sample type disabled
And: Reporting row with Specimen Type filled
When: User imports Config sheet
Then: Row shall be rejected
And: Error message shall indicate specimen not allowed

Test: REQ-CONFIGIO-014

Back to requirement

Test: Toggle ON ignores rows without extraction instruments

Given: Use Extraction Instruments toggle ON
And: Westgard Limits rows with and without Extraction Instruments
When: User imports alternative configuration
Then: Rows without Extraction Instruments shall have status "Ignored"

Test: Toggle OFF ignores rows with extraction instruments

Given: Use Extraction Instruments toggle OFF
And: Westgard Limits rows with Extraction Instruments
When: User imports alternative configuration
Then: Rows with Extraction Instruments shall have status "Ignored"

Test: REQ-CONFIGIO-015

Back to requirement

Test: Global row import creates non-strict records

Given: Configuration sheet with Reporting Cut-off row where MIX="Global", TARGET="Global", DYE="Global"
When: User imports the configuration
Then: The reporting cut-off shall be created as non-strict (is_strict=false)
And: The global mapper shall create strict records for each matching target

Test: Export represents non-strict rows as Global

Given: A non-strict cross contamination limit exists for the site
When: User exports the configuration
Then: The Cross Contamination Limits sheet shall show "Global" for mix, target, and dye columns for that row

Test: Orphaned non-strict rows are marked strict

Given: A non-strict Curve Control Limit that previously matched a global mapping
And: The global mapping has been removed
When: The mapper runs after save
Then: The formerly non-strict limit shall be marked strict (not deleted)

Test: REQ-CONFIGIO-016

Back to requirement

Test: New columns import successfully

Given: Control Labels sheet with verify_ic_target_is_positive=TRUE, verifiable_targets="Target A, Target B", associated_specimens="Serum, Plasma"
When: User imports the sheet
Then: The control label record shall have verify_ic_target_is_positive=true, verifiable_target_ids populated, and associated_specimen_ids populated

Test: Invalid verify-IC flag is rejected

Given: Control Labels sheet with verify_ic_target_is_positive="maybe"
When: User imports the sheet
Then: The row shall be rejected with error about invalid verify-IC option

Test: Invalid verifiable target is rejected

Given: Control Labels sheet with verify_ic_target_is_positive=TRUE and verifiable_targets containing a nonexistent target name
When: User imports the sheet
Then: The row shall be rejected with error listing the invalid targets

Test: Empty new columns are backward compatible

Given: Control Labels sheet with new columns left empty
When: User imports the sheet
Then: The row shall be imported successfully with no verification or associations applied

Test: REQ-CONFIGIO-017

Back to requirement

Test: Well migration on re-import

Given: Wells pointing at existing control labels
And: A Control Labels sheet with changed rows for the same role alias and mix
When: User imports the sheet
Then: Wells shall point at the new control labels (not the deleted ones)
And: No wells shall reference deleted control labels

Test: Full global mapping matching on re-import

Given: Multiple non-strict control labels exist for the same role but different configurations
When: A matching strict configuration is imported
Then: Only labels matching the full global mapping (including new fields) shall be marked strict

Test: REQ-CONFIGIO-018

Back to requirement

Test: Quantification scope replaces quantitative column

Given: Mix and Targets sheet with QUANTIFICATION_SCOPE="ALL" for Mix A
When: User imports the sheet
Then: Mix A shall have quantification_scope set to "ALL"
And: Any QUANTITATIVE column value shall be ignored

Test: Conflicting quantification scope is rejected

Given: Mix and Targets sheet where rows for Mix B have conflicting QUANTIFICATION_SCOPE values ("ALL" and "OFF")
When: User imports the sheet
Then: All rows for Mix B shall be rejected with error "Multiple quantification settings"

Test: Export includes new columns

Given: A mix with quantification_scope="BY_SPECIMEN" and quantification_method configured
When: User exports the configuration
Then: The Mix and Targets sheet shall include QUANTIFICATION_SCOPE and QUANTIFICATION_METHOD columns
And: The sheet shall not include a QUANTITATIVE column

Test: REQ-CONFIGIO-019

Back to requirement

Test: Error cascade prevention

Given: Cross Contamination Limits sheet with a row having invalid quant_or_ct value
When: User imports the sheet
Then: The row shall be rejected with quant_or_ct error only
And: No additional contamination value errors shall be reported for that row

Design Document	Relevant Sections
SDD Algorithms	Configuration Upload Algorithm, Configuration Export Algorithm, Westgard Rules
SDD Configuration	Control Labels Configurations, Combined Outcomes Excel schema

Appendix: Process Artifacts

Completion Checklist

Reviewer Notes

Consolidation: REQ-CONFIGIO-003

The following items from the source were consolidated into a single capability-level requirement:

Original Item	Source Reference	Disposition
REQ-CONFIGIO-003 (Mix/Target base)	3.0.0-Minimum Fluorescence, Is Quantitative, Passive Dye	Merged -> REQ-CONFIGIO-003
REQ-CONFIGIO-004 (Discrepancy settings)	3.0.0-Max CT for CLS/CT Discrepancy	Merged -> REQ-CONFIGIO-003 AC-06
REQ-CONFIGIO-024 (Prepend Cycles)	3.0.0-Cycle Counts for Targets	Merged -> REQ-CONFIGIO-003 AC-01, AC-07

Rationale: These items all describe import/export behavior for the same Mixes and Targets configuration sheet. They share the same validation patterns and workflow, differing only by column. Consolidation avoids requirement explosion for what is a single capability.

Reversibility: To restore original structure, reference:

Source: output/pilot/restructured/configio.md (REQ-CONFIGIO-003, 004, 024)
Confluence: Multiple pages for Mix/Target configuration import/export

Consolidation: REQ-CONFIGIO-004

The following items from the source were consolidated into a single capability-level requirement:

Original Item	Source Reference	Disposition
REQ-CONFIGIO-005 (Combined Outcomes Import)	3.0.0-Combined Outcomes - Import / Export (Rows 1-16)	Merged -> REQ-CONFIGIO-004
REQ-CONFIGIO-006 (Combined Outcomes Export)	3.0.0-Combined Outcomes - Import / Export (Row 17)	Merged -> REQ-CONFIGIO-004 AC-11
REQ-CONFIGIO-007 (IC Failed)	3.0.0-Combined Outcomes IC Fail Option	Merged -> REQ-CONFIGIO-004 AC-12
REQ-CONFIGIO-008 (Priority/Name)	3.0.0-Add Priority/Name - Import/Export	Merged -> REQ-CONFIGIO-004 AC-08, AC-10
REQ-CONFIGIO-009 (Discrepancy Required)	3.0.0-CLS/CT Discrepancy Required	Merged -> REQ-CONFIGIO-004 AC-09

Rationale: These five requirements all describe import/export behavior for the Combined Outcomes configuration sheet. They are additive column support for the same capability, not distinct system responsibilities.

Reversibility: To restore original structure, reference:

Source: output/pilot/restructured/configio.md (REQ-CONFIGIO-005 through 009)
Confluence: Multiple pages for Combined Outcomes configuration