Client Configuration
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: System-wide configuration settings and feature toggles Domain: CLIENTCFG
Statement
The system shall allow authorized users to manage system-wide configuration settings that control application behavior across all functional areas.
Configuration management includes viewing, editing, importing, and exporting settings for data handling rules, analysis parameters, display preferences, export formats, result management policies, and feature visibility controls. Only Super Users may modify configuration settings, and changes take effect immediately upon save unless otherwise specified.
Behavior Overview (Illustrative)
This diagram illustrates the high-level behavior. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Client Configuration | The collection of system-wide settings that control application behavior across all functional areas |
| Super User | A user with elevated privileges authorized to modify system configuration |
| Accession Number | A unique identifier assigned to a sample, subject to configurable character validation rules |
| Westgard Analysis | Statistical quality control analysis method with configurable ordering parameters |
| Feature Visibility Toggle | A configuration setting that controls whether a feature is available to users |
| Passive Target | A target type that may be included or excluded from target counts based on configuration |
Functional Requirements
Configuration Management (REQ-CLIENTCFG-001)
FR-CLIENTCFG-001 View and Edit Client Configuration Settings
The system shall allow authorized users to view and modify client configuration settings that control system behavior across functional areas.
Acceptance Criteria:
Display:
- The system shall display all available configuration settings organized by category
- The system shall support toggle-type settings (enable/disable)
- The system shall support selection-type settings (dropdown/choice lists)
Validation:
- The system shall validate setting values against defined option constraints
- The system shall reject setting values outside defined option sets
Persistence:
- The system shall persist configuration changes when the user confirms the save operation
Feature Toggles:
- The system shall apply feature visibility toggle changes to all users (not just the configuring user)
Feature Toggles Import/Export:
- Support import of feature toggle configuration via Excel
- Import columns: NAME, CODE, IS ENABLED
- NAME is read-only (display purposes); CODE is used for matching
- Validate CODE as required string that must match an existing feature in the system
- Validate CODE is not a restricted feature (use_multiple_sites, preserve_s3_structure_for_first_site)
- Validate IS ENABLED as boolean (accepts: true/false, 1/0, yes/no)
- Validate parent feature dependency: Cannot enable a child feature if its parent feature is disabled
- Invalid CODE (empty): Reject row with status "Feature: ignored: Feature code is required"
- Invalid CODE (restricted): Reject row with status "Feature: ignored: Feature is restricted and cannot be modified through import"
- Invalid CODE (unknown): Reject row with status "Feature: ignored: Feature does not exist in the system"
- Invalid IS ENABLED value: Reject row with status "Feature: ignored: Feature value must be a valid boolean (true/false, 1/0, yes/no). Previous value is kept."
- Invalid parent dependency: Reject row with status "Feature: ignored: Cannot enable '[code]' because parent feature '[parent]' is disabled"
- Export all configured features with columns: NAME, CODE, IS ENABLED
Constraints:
- The system shall disable Westgard second priority ordering setting when "Inherit Run Date" is enabled
- The system shall disable upload button import when "Prevent file import via drag and drop" setting is enabled
Error Handling
- Validation failure: The system shall display an error message identifying the invalid setting and constraint
- Save operation failure: The system shall display an error message and retain the user's unsaved changes
- Constraint violation (e.g., Westgard ordering when Inherit Run Date is enabled): The system shall prevent the change and indicate the constraint reason
Trace: Source: Client Configuration (Items 1.1, 1.5, 1.6, 2.1, 2.2, 3.1, 3.2, 3.3, 4.1, 4.2, 4.3, 5.1, 6.1, 7.1, 7.2, 8.1, 8.2, 8.3, 8.4) | CR: 2.17.0 Feature Visibility Toggles | Tests: See TC-CLIENTCFG-001 through TC-CLIENTCFG-016
Configuration Export (REQ-CLIENTCFG-002)
FR-CLIENTCFG-002 Export Client Configuration
The system shall allow authorized users to export the current client configuration settings to a file.
Acceptance Criteria:
- The system shall generate a configuration file containing all current settings
- The exported file shall include accession character validation settings
- The exported file shall include Westgard ordering priority settings
- The exported file shall include role priority resolution settings
- The export file format shall be consistent and parseable for re-import
Trace: Source: Client Configuration (Items 1.2, 2.3, 5.2) | Tests: See TC-CLIENTCFG-017, TC-CLIENTCFG-018
Configuration Import (REQ-CLIENTCFG-003)
FR-CLIENTCFG-003 Import Client Configuration
The system shall allow authorized users to import configuration settings from a previously exported configuration file.
Acceptance Criteria:
File Processing:
- The system shall accept configuration files in the supported export format
- The system shall update client configuration with values from the imported file
- The system shall update accession character validation settings from the import file
Validation:
- The system shall validate imported values against defined option constraints
- The system shall reject import values that are not in defined option sets
- The system shall provide feedback indicating import success or validation errors
Error Handling
- Invalid file format: The system shall reject the import and display "Invalid configuration file format"
- Invalid option value: The system shall reject the import and identify the invalid field and value
- Malformed or corrupted file: The system shall reject the import and display appropriate error message
Trace: Source: Client Configuration (Items 1.3, 1.4) | Tests: See TC-CLIENTCFG-019 through TC-CLIENTCFG-022
Non-Functional Requirements
NFR-CLIENTCFG-001 Configuration Operations Performance
Configuration operations shall conform to the global NFR performance standards defined in the system-wide Non-Functional Requirements section.
Applicable Operations:
- Configuration screen loading
- Configuration save operations
- Configuration import/export operations
Trace: Source: Client Configuration (General NFR expectations) | Related: Global NFR Performance Standards
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
| allowed_accession_characters | [] (empty) | Characters permitted in accession numbers (MULTISELECT) | REQ-CLIENTCFG-001 |
| fallback_shared_controls_enabled | false | Enable fallback shared controls | REQ-CLIENTCFG-001 |
| include_passive_targets_in_count | false | Include passive targets in target counts | REQ-CLIENTCFG-001 |
| prevent_drag_drop_import | false | Prevent file import via drag and drop (also prevents upload button) | REQ-CLIENTCFG-001 |
| westgard_second_priority_ordering | (deployment-specific) | Second priority of ordering for Westgard analysis | REQ-CLIENTCFG-001 |
| show_comment_count | (deployment-specific) | Show/hide comment count indicator | REQ-CLIENTCFG-001 |
| display_outcomes_as_hyperlinks | false | Display outcomes as clickable hyperlinks | REQ-CLIENTCFG-001 |
| export_quant_wells_separate_csv | false | Export quantitative wells to separate CSV file (separate_quantitative_csv_results) | REQ-CLIENTCFG-001 |
| lims_export_location | DOWNLOAD | LIMS export location (options: DOWNLOAD, SAVE_ON_CLOUD, SELECT_ON_DEMAND_II) | REQ-CLIENTCFG-001 |
| include_well_comments_in_export | false | Include well comments in outcome export (show_comments_in_outcome_export) | REQ-CLIENTCFG-001 |
| use_role_priority_for_resolution | false | Use role priority for conflict resolution | REQ-CLIENTCFG-001 |
| prevent_file_import_from_browser | false | When enabled, prevents users from uploading run files directly via the browser interface. Controls visibility of file import functionality. | REQ-CLIENTCFG-001 |
| count_system_generated_comments | false | When enabled, includes system-generated comments in comment counts (Display Options group). | REQ-CLIENTCFG-001 |
Feature Toggles (managed via Features table, not ClientConfiguration):
| Feature | Code | Default | Description | Affects |
|---|---|---|---|---|
| Trends Report Alerts | trends_report_alerts | false | Show/hide Alert feature | REQ-CLIENTCFG-001 |
| Trends Report Aggregate | trends_report_aggregate | (inherits from trends_report) | Show/hide Trends report aggregation | REQ-CLIENTCFG-001 |
| User Tagging in Comments | user_tagging_in_comments | true | Enable comment notification/tagging | REQ-CLIENTCFG-001 |
| Help Items | help_items | true | Show/hide context sensitive help | REQ-CLIENTCFG-001 |
| Activate Archive Mode | activate_archive_mode | false | Enable archived mode functionality | REQ-CLIENTCFG-001 |
| Westgards | westgard | false | Enables the Westgards tab on Run View, showing Westgard rule violations. Also enables Westgards section in run print options. | REQ-CLIENTCFG-001 |
| Assay Summary | assay_summary | false | Enables the Assay Summary tab on Run View displaying target-level summary statistics. Also enables Assay Summary section in run print options. | REQ-CLIENTCFG-001 |
| Outcomes Report | outcomes_report | false | Enables the Outcomes Report page in the sidebar navigation. Controls clickable outcome frequency in Trends Report. | REQ-CLIENTCFG-001 |
| Run Quick Filters | run_quick_filters | false | Enables clickable cells in Outcome Summary and Assay Summary tables for quick filtering of wells. | REQ-CLIENTCFG-001 |
| Trends Report AI Assistant | trends_report_ai_assistant | true | Enables AI-powered assistance within the Trends Report Builder. Child of trends_report_builder (disabled when parent is disabled). | REQ-CLIENTCFG-001 |
| Trends Report Builder | trends_report_builder | false | Enables the Report Builder tab in Trends Report for creating custom trend analyses. Child of trends_report. Parent of trends_report_ai_assistant. | REQ-CLIENTCFG-001 |
| Run Plate Map | run_plate_map | false | Enables the Plate Map tab on Run View showing 96-well plate visualization. Also enables Plate Map section in run print options. | REQ-CLIENTCFG-001 |
| LJ Report | lj_report | false | Enables the LJ (Levey-Jennings) Report page in sidebar navigation. Also enables "Open LJ Report" button in Westgards panel. | REQ-CLIENTCFG-001 |
| Outcome Summary | outcome_summary | false | Enables the Outcome Summary tab on Run View displaying outcome-level aggregations. Also enables Outcome Summary section in run print options. | REQ-CLIENTCFG-001 |
Note: Default values sourced from database migrations. Some values may be deployment-specific where noted.
Assumptions
- Users accessing configuration modification functions have Super User role permissions
- Configuration changes take effect immediately upon save unless otherwise specified
- Configuration export format is consistent and reversible (export/import round-trip preserves settings)
- Network connectivity is available for cloud-based export operations
UI Notes (Illustrative)
FR-CLIENTCFG-001 UI Specifications
Implementation: resources/frontend/src/views/ClientConfiguration.vue
Layout Structure:
- Screen title: "Configurations and Feature Toggles"
- Two-column layout: Left column (5/12 width) for configuration settings, Right column (5/12 width) for feature toggles
- Search box at top for filtering configurations and features
- Help button (conditional on help_items feature)
Configuration Groups (ClientConfiguration model GROUPS):
- Login/User Management Options (order: 1)
- Import/Data Options (order: 2)
- Export Options (order: 3)
- Display Options (order: 4)
- Edit/Manage Results Options (order: 5)
- Westgard Options (order: 6)
Component Hierarchy:
ClientConfigurationGroup.vue- Renders grouped settingsClientConfigurationSetting.vue- Individual setting controlApplicationFeatureToggle.vue- Feature toggle switch
Configuration Types (ClientConfiguration model TYPES):
- BOOLEAN (1) - Toggle switch
- TEXT (2) - Text input
- OPTIONS (3) - Dropdown select
- MULTISELECT (4) - Multi-select dropdown
Implementation (Illustrative)
| Component | Type | Location | Requirements | Description |
|---|---|---|---|---|
| ClientConfiguration | Model | code/app/ClientConfiguration.php | 001, 002, 003 | Client configuration entity with type casting |
| ClientConfigurationsController | Controller | code/app/Http/Controllers/ | 001 | Configuration CRUD operations |
| ClientConfigurationSettingsController | Controller | code/app/Http/Controllers/ | 001 | Lightweight key-value settings endpoint |
| ConfigDataController | Controller | code/app/Http/Controllers/ | 003 | Import/export controller (shared with kit config) |
| UpdateClientConfigurationAction | Action | code/app/Actions/ | 001 | Update with cascade handling |
| GetClientConfigurationsAction | Action | code/app/Actions/ | 001 | Retrieve with computed disabled state |
| ClientConfigurationEnableStateChecker | Action | code/app/Actions/ | 001 | Runtime feature flag evaluation |
| DeleteClientConfigurationsAction | Action | code/app/Actions/ | 001 | Configuration reset (factory reset) |
| AffectedClientConfigurations | Service | code/app/Services/ | 001 | Dependency rules definition |
| ClientConfigurationParentService | Service | code/app/Services/ | 001 | Dependency chain navigation |
| ClientConfigurationsExport | Export | code/app/Exports/ | 002 | Excel export sheet |
| ClientConfigurationsImportSheet | Import | code/app/Imports/ | 003 | Excel import with validation |
| ClientConfigurationValidator | Validator | code/app/Validators/ | 003 | Import row validation |
Frontend Components:
| Component Type | Location |
|---|---|
| View | views/ClientConfiguration.vue |
| Components | components/client-configurations/ |
| Store | store/modules/features.js |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-CLIENTCFG-001 | View and Edit Client Configuration Settings | Test | ClientConfiguration, ClientConfigurationsController, ClientConfigurationSettingsController, UpdateClientConfigurationAction, GetClientConfigurationsAction, AffectedClientConfigurations, ClientConfigurationParentService | TC-CLIENTCFG-001 through TC-CLIENTCFG-016 | Draft |
| REQ-CLIENTCFG-002 | Export Client Configuration | Test | ClientConfigurationsExport | TC-CLIENTCFG-017, TC-CLIENTCFG-018 | Draft |
| REQ-CLIENTCFG-003 | Import Client Configuration | Test | ConfigDataController, ClientConfigurationsImportSheet, ClientConfigurationValidator | TC-CLIENTCFG-019 through TC-CLIENTCFG-022 | Draft |
| NFR-CLIENTCFG-001 | Configuration Operations Performance | Test | [Global NFR Standards] | [Pending] | Draft |
Notes
- Only super users have access to modify configuration settings
- Feature visibility toggles control which features are available to users throughout the application
- Exported configuration can be used as a template for other client setups
- Import validation ensures data integrity before applying changes
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| OQ-001 | Default values marked as "deployment-specific" need confirmation from SME | Configuration Options | @SME-TBD | TBD |
Acceptance Tests
Test: REQ-CLIENTCFG-001
Test: Access configuration screen
Given: User logged in as super user
When: Navigate to Client Configuration screen
Then: Configuration settings are displayed organized by category
Test: Modify allowed characters for accession
Given: Super user on Client Configuration screen
When: Define allowed characters for accession numbers
And: Save configuration
Then: The allowed characters setting is persisted
Test: Toggle fallback shared controls
Given: Super user on Client Configuration screen
When: Enable fallback shared controls option
And: Save configuration
Then: Fallback shared controls are enabled system-wide
When: Disable fallback shared controls option
And: Save configuration
Then: Fallback shared controls are disabled system-wide
Test: Configure passive targets in count
Given: Super user on Client Configuration screen
When: Enable "Include passive targets in targets count"
And: Save configuration
Then: Passive targets are included in target counts
When: Disable "Include passive targets in targets count"
And: Save configuration
Then: Passive targets are excluded from target counts
Test: Configure Westgard second priority ordering
Given: Super user on Client Configuration screen
And: "Inherit Run Date" is disabled
When: Change second priority of ordering for Westgard
And: Save configuration
Then: The Westgard ordering priority is updated
Test: Westgard ordering constraint
Given: Super user on Client Configuration screen
And: "Inherit Run Date" is enabled
When: Attempt to change second priority of ordering for Westgard
Then: The change is prevented (field disabled or validation error)
Test: Toggle comment count display
Given: Super user on Client Configuration screen
When: Enable "Show comment count" option
And: Save configuration
Then: Comment counts are displayed throughout the application
When: Disable "Show comment count" option
And: Save configuration
Then: Comment counts are hidden throughout the application
Test: Toggle outcomes as hyperlinks
Given: Super user on Client Configuration screen
When: Enable "Display outcomes as hyperlinks"
And: Save configuration
Then: Outcomes appear as clickable hyperlinks
When: Disable "Display outcomes as hyperlinks"
And: Save configuration
Then: Outcomes appear as plain text
Test: Configure export options
Given: Super user on Client Configuration screen
When: Enable "Export quantitative wells to separate CSV"
And: Select LIMS export location as "Cloud"
And: Enable "Include well comments in outcome export"
And: Save configuration
Then: All export options are persisted as configured
Test: Configure role priority for resolution
Given: Super user on Client Configuration screen
When: Enable "Use role priority for resolution"
And: Save configuration
Then: Role priority is used when resolving conflicts
Test: Prevent file import via drag and drop
Given: Super user on Client Configuration screen
When: Enable "Prevent file import via drag and drop"
And: Save configuration
Then: Users cannot import files via drag and drop
And: Users cannot import files via upload button
Test: Configure feature visibility - Alert
Given: Super user on Client Configuration screen
When: Enable "Hide Alert feature"
And: Save configuration
Then: Alert feature is hidden from all users
Test: Configure feature visibility - Trends
Given: Super user on Client Configuration screen
When: Enable "Hide Trends report aggregation"
And: Save configuration
Then: Trends report aggregation is hidden from all users
Test: Configure feature visibility - Comments
Given: Super user on Client Configuration screen
When: Enable "Hide Comment notification/display"
And: Save configuration
Then: Comment notifications and display are hidden from all users
Test: Configure feature visibility - Help
Given: Super user on Client Configuration screen
When: Enable "Hide Context sensitive help"
And: Save configuration
Then: Context sensitive help is hidden from all users
Test: Configure archive mode
Given: Super user on Client Configuration screen
When: Enable "Allow Archived Mode"
And: Save configuration
Then: Archive functionality is enabled for the client
Test: REQ-CLIENTCFG-002
Test: Export configuration
Given: Super user on Client Configuration screen
When: User initiates configuration export
Then: Configuration file is downloaded
And: File contains all current configuration settings
Test: Verify exported content
Given: Client configuration has specific settings:
- Allowed characters: "A-Z, 0-9, -"
- Second priority ordering: "Run Date"
- Use role priority: Enabled
When: Export configuration
Then: Exported file contains:
- Allowed characters setting: "A-Z, 0-9, -"
- Second priority ordering: "Run Date"
- Use role priority: Enabled
Test: REQ-CLIENTCFG-003
Test: Import valid configuration
Given: Super user on Client Configuration screen
And: Valid configuration export file is available
When: Import the configuration file
Then: Configuration settings are updated from the file
And: Success message is displayed
Test: Import with allowed characters
Given: Configuration file contains allowed characters: "A-Z, 0-9"
When: Import the configuration file
Then: Allowed characters for accession is set to "A-Z, 0-9"
Test: Import validation - invalid values
Given: Configuration file contains an invalid value for a dropdown field
(e.g., export location = "InvalidOption")
When: Import the configuration file
Then: Import is rejected
And: Validation error message indicates the invalid field and value
Test: Import validation - format error
Given: Configuration file is malformed or corrupted
When: Attempt to import the configuration file
Then: Import fails with appropriate error message
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Configuration | Client Configuration, Environment Variables |
| SDD Deployment Operations | Laravel Environment Variables (APP_URL) |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion)
- UI details are fully demoted to Illustrative section
- Configuration options are not encoded as requirements
- Acceptance criteria describe behavior, not UI mechanics
- Every requirement has acceptance criteria and source traceability
- Error handling addressed for I/O, validation, and external system requirements
- Open questions documented with owners assigned
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- All refinements folded into Acceptance Criteria
- Traceability matrix is complete
Reviewer Notes
No consolidations were performed during this conversion. The three source requirements represent distinct system capabilities:
| Source Requirement | Capability | Disposition |
|---|---|---|
| REQ-CLIENTCFG-001 | View and edit configuration | Preserved as FR-CLIENTCFG-001 |
| REQ-CLIENTCFG-002 | Export configuration | Preserved as FR-CLIENTCFG-002 |
| REQ-CLIENTCFG-003 | Import configuration | Preserved as FR-CLIENTCFG-003 |
Rationale: These requirements represent genuinely distinct system capabilities and do not exhibit requirement explosion patterns. Each requirement addresses a different user workflow (CRUD, export, import) with different acceptance criteria and error conditions.
Format Changes:
- Added Statement section for quick understanding of domain scope
- Added Mermaid flowchart showing configuration management flow
- Grouped acceptance criteria by concern (Display, Validation, Persistence, etc.)
- Moved tests to end with back-links to requirements
- Changed "Non-normative" to "Illustrative" per terminology guidelines
- Added blank lines after AC headers for proper PDF rendering
Reversibility: Source file preserved at output/srs/client-config.md