Skip to main content
Version: Next

Specimen Type Management

Version: v3.1.0 Status: Normative (text), Illustrative (diagrams only) Scope: Specimen type CRUD, target name suffix-to-specimen mapping, and suffix-based specimen derivation during import Domain: SPECIMEN

Statement​

The system shall provide SUPER_ADMIN users with dedicated configuration pages for managing specimen types and mapping target name suffixes to specimen types, enabling automatic specimen derivation during runfile import.

In v3.1.0, specimen management is elevated from a simple import-only entity (see REQ-KITCFG-031) to a full CRUD workflow accessible through Config Mode's "Other Settings" menu (BT-5894). The target name suffix mapping introduces a paradigm where specimen types are automatically derived from target name patterns during import, eliminating the need for manual specimen assignment. A target whose name ends with a configured suffix is automatically associated with the corresponding specimen type, enabling specimen-specific reporting cut-offs, combined outcomes, and rule mappings without manual intervention.

Behavior Overview (Illustrative)​

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

Definitions​

TermDefinition
Specimen TypeA site-scoped classification for samples (e.g., "Nasopharyngeal Swab", "Plasma", "Serum") that controls which reporting and analysis configurations apply
Target Name SuffixAn uppercase string pattern matched against the end of target names to automatically derive a specimen type during import
Use QuantificationA boolean property on specimen types (added in v3.1.0) controlling whether a specimen type supports quantification workflows
Suffix MappingAn association between a target name suffix and a specimen type, unique per site (case-insensitive)
Working SetIn-memory collection of pending specimen or mapping changes that are batched and saved together

Functional Requirements​

Specimen Types Page Access (REQ-SPECIMEN-001)​

FR-SPECIMEN-001 Access Specimen Types Page​

The system shall provide a Specimen Types configuration page accessible from the Config Mode sidebar "Other Settings" menu, restricted to SUPER_ADMIN users.

Acceptance Criteria:

Access Control:

  • The "Specimen types" link shall appear in the "Other Settings" submenu for SUPER_ADMIN users only
  • Users without SUPER_ADMIN role shall not see the "Specimen types" link
  • The page shall be served at route /specimens?config_mode=true

Error Handling:

  • Non-SUPER_ADMIN user attempts direct navigation: Access denied

Trace: Source: 3.1.0-Specimen Types (Row 1) | Jira: BT-5894 | SRS: REQ-KITCFG-031 (predecessor) | Tests: Pending

Specimen Types Table (REQ-SPECIMEN-002)​

FR-SPECIMEN-002 Display Specimen Types Table​

The system shall display a table listing all specimen types configured for the user's site, with columns for specimen name and quantification status.

Acceptance Criteria:

Display:

  • Display all specimens for the user's logged-in site in a table
  • Table columns: Specimen Type (specimen_name, 50% width) and Use Quantification (use_quant displayed as "TRUE"/"FALSE", 50% width)
  • Page header shall include a sticky title "Specimen types" with Add and Edit action buttons
  • Show empty table when no specimens exist for the site

Site Scoping:

  • All specimen data shall be scoped to the user's site in a multi-tenant environment
  • API queries filter by the user's logged_in_site_id
  • Attempts to access or modify specimens belonging to a different site shall return a 404 error

Trace: Source: 3.1.0-Specimen Types (Rows 2-3, 10) | Jira: BT-5894 | Tests: Pending

Add Specimen (REQ-SPECIMEN-003)​

FR-SPECIMEN-003 Create New Specimen Type​

The system shall allow SUPER_ADMIN users to create new specimen types via an "Add" side panel with name uniqueness and length validation.

Acceptance Criteria:

Add Panel:

  • Clicking the "Add" button (plus icon) in the sticky header shall open a side panel in add mode with header "New specimen"
  • The panel shall contain: Specimen name (text input, required, editable) and Use quantification (toggle, default false)
  • The new specimen shall be added to a pending working set on "Confirm Changes"

Validation:

  • Specimen name is required and must be unique per site (case-insensitive)
  • Specimen name must not exceed 255 characters
  • Duplicate name shall produce a 422 error from the API

Batch Save:

  • A "Save all confirmed changes" button shall execute all pending creates (POST) and updates (PUT) in parallel
  • After save, a success message shall be shown and the table shall refresh from the server
  • The save button shall not be actionable when no changes have been confirmed

Error Handling:

  • Duplicate specimen name: API returns 422, error message displayed to user
  • Empty specimen name: Validation prevents submission

Trace: Source: 3.1.0-Specimen Types (Rows 4, 6, 9) | Jira: BT-5894 | Tests: Pending

Edit Specimen (REQ-SPECIMEN-004)​

FR-SPECIMEN-004 Edit Existing Specimen Type​

The system shall allow SUPER_ADMIN users to edit existing specimen types via an "Edit" side panel, with the specimen name immutable after creation.

Acceptance Criteria:

Edit Panel:

  • Selecting a row in the table and clicking the "Edit" button (pencil icon) shall open a side panel in edit mode with header "Edit specimen"
  • Specimen name shall be displayed as a read-only label (immutable after creation)
  • Use quantification shall be displayed as an editable toggle
  • "Confirm Changes" button shall be disabled if the form is invalid or unmodified
  • "Cancel Changes" button shall revert to the original state

Working Set:

  • Confirmed edits shall be tracked in a working set for batch save
  • Footer navigation (Next/Previous) shall allow navigating between pending changes
  • Unsaved changes shall trigger a warning dialog on panel close with Save, Discard, and Cancel options

Trace: Source: 3.1.0-Specimen Types (Rows 5, 7, 8) | Jira: BT-5894 | Tests: Pending

Delete Specimen (REQ-SPECIMEN-005)​

FR-SPECIMEN-005 Delete Specimen Type with Association Warning​

The system shall allow SUPER_ADMIN users to delete specimen types, displaying a warning when the specimen has existing associations (suffix mappings, test codes, reporting cut-offs, or combined outcomes).

Acceptance Criteria:

  • Deletion shall be available for specimens without blocking constraints
  • When a specimen has associations, the system shall display a warning indicating the scope of downstream impact before confirming deletion
  • Deletion shall remove the specimen from the site's configuration

Error Handling:

  • Specimen has associations: Warning displayed before deletion confirmation

Trace: Source: 3.1.0-Specimen Types (Row 5, implied from design spec) | Jira: BT-5894 | Tests: Pending

Target Suffix Page Access (REQ-SPECIMEN-006)​

FR-SPECIMEN-006 Access Target Name Suffix to Specimen Page​

The system shall provide a Target Name Suffix to Specimen page accessible from the Config Mode sidebar "Other Settings" menu, restricted to SUPER_ADMIN users, and conditionally visible only when the specimen type source is configured as "From Target Suffix".

Acceptance Criteria:

Access Control:

  • The "Target Name Suffix to Specimen" link shall appear in the "Other Settings" submenu for SUPER_ADMIN users only
  • The link shall only be visible when use_sample_type client configuration equals "From Target Suffix"
  • Users without SUPER_ADMIN role shall not see the link regardless of configuration
  • The page shall be served at route /target-name-suffix-to-specimen?config_mode=true

Trace: Source: 3.1.0-Target Name Suffix to Specimen (Row 1) | Jira: BT-5894 | Tests: Pending

Target Suffix Mapping Table (REQ-SPECIMEN-007)​

FR-SPECIMEN-007 Display Target Suffix Mapping Table​

The system shall display a table listing all target name suffix-to-specimen mappings for the user's site.

Acceptance Criteria:

Display:

  • Display all suffix-to-specimen mappings for the user's site in a table
  • Table columns: Target Name Suffix (40% width, displayed in uppercase), Specimen Name (40% width, "-" if empty), Actions (20% width, delete button)
  • Page header shall include a sticky title "Target Name Suffixes" with an "Add" button
  • Show "No records available" message when no mappings exist
  • Display a skeleton loader during data fetch

Site Scoping:

  • All suffix data shall be scoped to the user's site
  • Unique constraint: (target_name_suffix, site_id) at the database level

Trace: Source: 3.1.0-Target Name Suffix to Specimen (Rows 2-3, 10) | Jira: BT-5894 | Tests: Pending

Add Target Suffix Mapping (REQ-SPECIMEN-008)​

FR-SPECIMEN-008 Create Target Name Suffix to Specimen Mapping​

The system shall allow SUPER_ADMIN users to create new suffix-to-specimen mappings via an "Add" side panel with suffix uniqueness validation (case-insensitive) and optional inline specimen creation.

Acceptance Criteria:

Add Panel:

  • Clicking the "Add" button shall open a side panel with header "New mapping"
  • The panel shall contain: Specimen dropdown (select existing or create new inline) and Target Name Suffix text input (required)
  • All suffixes shall be normalized to UPPERCASE before storage
  • Suffix must be unique per site (case-insensitive); duplicate submission shall display validation error "Suffix should be unique (case-insensitive)"

Inline Specimen Creation:

  • The add form shall support creating a new specimen directly without leaving the page
  • Inline creation fields: Specimen name (text input, required) and Use quantification (toggle)
  • After creation, the new specimen shall appear in the Specimen dropdown for selection

Confirmation:

  • Clicking "Add Mapping" shall submit the mapping via API
  • On success: message "Mapping added successfully.", table refreshes, panel closes

Error Handling:

  • Duplicate suffix (case-insensitive): Validation error displayed, mapping not created
  • Missing required fields: Form validation prevents submission

Trace: Source: 3.1.0-Target Name Suffix to Specimen (Rows 4-5) | Jira: BT-5894 | Tests: Pending

Edit Target Suffix Mapping (REQ-SPECIMEN-009)​

FR-SPECIMEN-009 Edit Existing Target Name Suffix to Specimen Mapping​

The system shall allow SUPER_ADMIN users to edit existing suffix-to-specimen mappings via an "Edit" side panel, with the suffix value immutable after creation.

Acceptance Criteria:

Edit Panel:

  • Clicking a mapping row in the table shall open a side panel displaying the selected suffix value as header
  • Target Name Suffix shall be displayed as a disabled (read-only) field
  • Specimen shall be editable via a dropdown selector (required)
  • "Confirm Changes" button shall be disabled if the form is invalid or unmodified
  • "Cancel Changes" button shall revert to the original specimen selection

Batch Save:

  • Confirmed edits shall be tracked in a working set
  • A "Save" button in the footer shall send all modified mappings in a single API call (PUT)
  • Backend shall validate for duplicate suffixes (excluding records being updated), case-insensitive
  • On success: message "Target name suffix to specimen mappings saved.", table refreshes, panel closes
  • Footer navigation (Next/Previous) shall allow navigating between mappings

Unsaved Changes:

  • Closing the edit panel with unsaved modifications shall trigger a warning dialog with Save, Discard, and Cancel options

Trace: Source: 3.1.0-Target Name Suffix to Specimen (Rows 6-7, 9) | Jira: BT-5894 | Tests: Pending

Delete Target Suffix Mapping (REQ-SPECIMEN-010)​

FR-SPECIMEN-010 Delete Target Name Suffix to Specimen Mapping​

The system shall allow SUPER_ADMIN users to delete suffix-to-specimen mappings with a confirmation dialog.

Acceptance Criteria:

  • Clicking the delete button on a mapping row shall display a confirmation dialog: "Are you sure you want to delete the mapping for suffix '{suffix}'?"
  • Confirming deletion shall send DELETE request to API; backend verifies mapping belongs to user's site (404 if mismatch)
  • On success: HTTP 204, message "Mapping deleted successfully.", table refreshes, selection clears if the deleted mapping was selected
  • Cancelling the dialog shall leave the mapping unchanged

Trace: Source: 3.1.0-Target Name Suffix to Specimen (Row 8) | Jira: BT-5894 | Tests: Pending

Suffix Matching During Import (REQ-SPECIMEN-011)​

FR-SPECIMEN-011 Automatic Specimen Type Assignment via Target Name Suffix Matching​

The system shall automatically associate a specimen type with a target during runfile import when the target name ends with a configured suffix, enabling downstream specimen-specific configuration without manual assignment.

Acceptance Criteria:

Matching Logic:

  • During import, the system shall compare each target name against all configured suffixes for the site
  • Matching shall be performed against the uppercase-normalized suffix stored in the database
  • When a target name ends with a configured suffix, the system shall assign the associated specimen type to that target's observations
  • When no suffix matches, no specimen type is assigned (existing behavior preserved)

Downstream Effects:

  • Assigned specimen types shall be used by reporting cut-offs (REQ-KITCFG-016), combined outcomes (REQ-KITCFG-011), and rule mappings (REQ-KITCFG-024) for specimen-specific configuration selection
  • Specimen-specific configuration shall take precedence over non-specimen ("Any") configuration when both exist

Trace: Source: 3.1.0-Target Name Suffix to Specimen (Rows implied from design spec) | Jira: BT-5894 | SDS: [Pending] | STD: [Pending] | Related: configio.md (import integration) | Tests: Pending

Help Data Toggle (REQ-SPECIMEN-012)​

FR-SPECIMEN-012 Help Data Toggle for Target Suffix Page​

The system shall provide a feature-flag-gated help data toggle on the Target Name Suffix to Specimen page.

Acceptance Criteria:

  • The help data toggle shall be visible only when the help_items feature flag is enabled for the site
  • Activating the toggle shall display contextual help information for the suffix mapping page
  • Deactivating the toggle shall hide the help content

Trace: Source: 3.1.0-Target Name Suffix to Specimen (Row 7 implied) | Jira: BT-5894 | Tests: Pending

Configuration Options​

OptionDefaultDescriptionAffects
use_sample_typefalse/off/"From Target Suffix"Enables specimen type features; when set to "From Target Suffix", enables the Target Suffix pageREQ-SPECIMEN-001, REQ-SPECIMEN-006, REQ-SPECIMEN-011
help_itemsfalseFeature flag enabling help data widgets on configuration pagesREQ-SPECIMEN-012

Assumptions​

  • Users accessing Specimen Type Management require SUPER_ADMIN role (Config Mode sidebar restricts access)
  • Specimen types are site-scoped; each site maintains an independent set of specimen types
  • Target name suffixes are stored and matched in UPPERCASE; all comparisons are case-insensitive
  • The use_sample_type configuration must be set to "From Target Suffix" for the suffix mapping page to appear
  • Specimen types created via inline creation on the suffix mapping page follow the same validation rules as the dedicated Specimen Types page
  • The use_quant field on specimens (v3.1.0 addition) defaults to false and controls downstream quantification workflow availability

UI Notes (Illustrative)​

FR-SPECIMEN-001, FR-SPECIMEN-002 UI Specifications​

Specimen Types Page Layout:

  • Sticky header with title "Specimen types" and action buttons (Add with plus icon, Edit with pencil icon)
  • SpecimensTable component below header
  • Rows are clickable for selection (used with Edit button)

FR-SPECIMEN-003, FR-SPECIMEN-004 UI Specifications​

Side Panel (Add/Edit):

  • SpecimenEditWidget component wrapping SpecimenForm (VeeValidate-powered)
  • Add mode header: "New specimen"; Edit mode header: "Edit specimen"
  • Footer: FooterEditWidget with Next/Previous navigation between pending changes, showing position counter
  • "Save all confirmed changes" button in footer for batch persistence
  • Unsaved changes dialog: Save / Discard / Cancel options

FR-SPECIMEN-006, FR-SPECIMEN-007 UI Specifications​

Target Name Suffix Page Layout:

  • Sticky header with title "Target Name Suffixes" and "Add" button
  • TargetNameSuffixToSpecimenTable component below header
  • Skeleton loader during initial data fetch
  • "No records available" empty state

FR-SPECIMEN-008 UI Specifications​

Add Mapping Panel:

  • BaseEditWidget wrapping TargetNameSuffixToSpecimenAddForm
  • Specimen dropdown with inline "Add" toggle for creating new specimens without leaving the page
  • Target Name Suffix text input with case-insensitive uniqueness validation

FR-SPECIMEN-009, FR-SPECIMEN-010 UI Specifications​

Edit/Delete Interactions:

  • Click row to select and open edit panel (BaseEditWidget wrapping TargetNameSuffixToSpecimenEditWidget)
  • Suffix shown as disabled field; specimen editable via dropdown
  • Delete button per row with confirmation dialog showing the suffix value

Implementation (Illustrative)​

ComponentTypePathRequirements
Specimens.vueVue Pageresources/frontend/src/views/Specimens.vueREQ-SPECIMEN-001 through REQ-SPECIMEN-005
SpecimensTableVue Componentresources/frontend/src/components/specimens/SpecimensTable.vueREQ-SPECIMEN-002
SpecimenEditWidgetVue Componentresources/frontend/src/components/specimens/SpecimenEditWidget.vueREQ-SPECIMEN-003, REQ-SPECIMEN-004
SpecimenFormVue Componentresources/frontend/src/components/specimens/SpecimenForm.vueREQ-SPECIMEN-003, REQ-SPECIMEN-004
TargetNameSuffixToSpecimen.vueVue Pageresources/frontend/src/views/TargetNameSuffixToSpecimen.vueREQ-SPECIMEN-006 through REQ-SPECIMEN-010
TargetNameSuffixToSpecimenTableVue Componentresources/frontend/src/components/target-name-suffix/TargetNameSuffixToSpecimenTable.vueREQ-SPECIMEN-007
TargetNameSuffixToSpecimenAddFormVue Componentresources/frontend/src/components/target-name-suffix/TargetNameSuffixToSpecimenAddForm.vueREQ-SPECIMEN-008
TargetNameSuffixToSpecimenEditWidgetVue Componentresources/frontend/src/components/target-name-suffix/TargetNameSuffixToSpecimenEditWidget.vueREQ-SPECIMEN-009
Specimen.phpModelapp/Models/Specimen.phpREQ-SPECIMEN-002, REQ-SPECIMEN-003, REQ-SPECIMEN-004, REQ-SPECIMEN-005
TargetNameSuffixToSpecimen.phpModelapp/Models/TargetNameSuffixToSpecimen.phpREQ-SPECIMEN-007 through REQ-SPECIMEN-011
SpecimensControllerControllerapp/Http/Controllers/SpecimensController.phpREQ-SPECIMEN-001 through REQ-SPECIMEN-005
TargetNameSuffixToSpecimenControllerControllerapp/Http/Controllers/TargetNameSuffixToSpecimenController.phpREQ-SPECIMEN-006 through REQ-SPECIMEN-010

Traceability Matrix​

RequirementTitleVerificationImplementationTest CasesStatus
REQ-SPECIMEN-001Specimen Types Page AccessTestSpecimensController, Specimens.vue[Pending]Draft
REQ-SPECIMEN-002Specimen Types TableTestSpecimensTable, Specimen.php[Pending]Draft
REQ-SPECIMEN-003Add SpecimenTestSpecimenEditWidget, SpecimenForm[Pending]Draft
REQ-SPECIMEN-004Edit SpecimenTestSpecimenEditWidget, SpecimenForm[Pending]Draft
REQ-SPECIMEN-005Delete Specimen with WarningTestSpecimensController[Pending]Draft
REQ-SPECIMEN-006Target Suffix Page AccessTestTargetNameSuffixToSpecimen.vue[Pending]Draft
REQ-SPECIMEN-007Target Suffix Mapping TableTestTargetNameSuffixToSpecimenTable[Pending]Draft
REQ-SPECIMEN-008Add Target Suffix MappingTestTargetNameSuffixToSpecimenAddForm[Pending]Draft
REQ-SPECIMEN-009Edit Target Suffix MappingTestTargetNameSuffixToSpecimenEditWidget[Pending]Draft
REQ-SPECIMEN-010Delete Target Suffix MappingTestTargetNameSuffixToSpecimenController[Pending]Draft
REQ-SPECIMEN-011Suffix Matching During ImportTestTargetNameSuffixToSpecimen.php[Pending]Draft
REQ-SPECIMEN-012Help Data ToggleTestTargetNameSuffixToSpecimen.vue[Pending]Draft

Notes​

  • REQ-SPECIMEN-001 through REQ-SPECIMEN-005 supersede the v3.0.0 import-only specimen management described in REQ-KITCFG-031; v3.1.0 adds a dedicated CRUD UI, the use_quant field, and Config Mode integration
  • Specimens created inline from the suffix mapping page (REQ-SPECIMEN-008) are identical to those created from the Specimen Types page (REQ-SPECIMEN-003); they share the same API and validation rules
  • The suffix matching logic (REQ-SPECIMEN-011) integrates with the runfile import pipeline documented in configio.md
  • All specimen and suffix data is site-scoped with database-level unique constraints

Open Questions​

IDQuestionSourceOwnerDate Raised
OQ-001Should REQ-KITCFG-031 (v3.0.0 import-only specimens) be formally deprecated in kitcfg.md now that REQ-SPECIMEN-001 through REQ-SPECIMEN-005 provide full CRUD?v3.1.0 inventoryTBD2026-03-06
OQ-002Should suffix matching (REQ-SPECIMEN-011) handle multiple suffix matches (longest match wins, or error)? Source material does not specify conflict resolution.3.1.0 ConfluenceTBD2026-03-06

Acceptance Tests​

Test: REQ-SPECIMEN-001​

Back to requirement

Test: SUPER_ADMIN can access Specimen Types page

Given: User logged in as SUPER_ADMIN in Config Mode
When: User hovers over "Other Settings" in the config sidebar
Then: "Specimen types" link is visible in the submenu
When: User clicks "Specimen types"
Then: The Specimen Types page loads at /specimens?config_mode=true

Test: Non-SUPER_ADMIN cannot see Specimen Types link

Given: User logged in as CLIENT_CONFIG in Config Mode
When: User hovers over "Other Settings" in the config sidebar
Then: "Specimen types" link is not visible

Test: REQ-SPECIMEN-002​

Back to requirement

Test: Display specimens for user's site

Given: User belongs to Site A
And: Site A has specimens: "Plasma" (use_quant=true), "Serum" (use_quant=false)
When: User navigates to the Specimen Types page
Then: Table displays two rows:
  | Specimen Type | Use quantification |
  | Plasma        | TRUE               |
  | Serum         | FALSE              |

Test: Site isolation

Given: User belongs to Site A
And: Site B has specimen "CSF" not present in Site A
When: User fetches specimens
Then: "CSF" does not appear in the table

Test: REQ-SPECIMEN-003​

Back to requirement

Test: Add new specimen with valid name

Given: User is on the Specimen Types page
When: User clicks the "Add" button
Then: Add panel opens with header "New specimen"
When: User enters specimen name "Nasopharyngeal Swab"
And: User leaves "Use quantification" toggle off
And: User clicks "Confirm Changes"
And: User clicks "Save all confirmed changes"
Then: The new specimen appears in the table with use_quant = FALSE

Test: Reject duplicate specimen name

Given: Specimen "Plasma" already exists for the site
When: User tries to add a specimen named "Plasma"
And: User clicks "Confirm Changes" and then "Save all confirmed changes"
Then: API returns 422 error
And: Error message is displayed

Test: REQ-SPECIMEN-004​

Back to requirement

Test: Edit specimen use_quant toggle

Given: Specimen "Plasma" exists with use_quant = false
When: User selects "Plasma" row and clicks "Edit"
Then: Edit panel opens with specimen name as read-only label
And: "Use quantification" toggle is off
When: User toggles "Use quantification" on
And: User clicks "Confirm Changes"
And: User clicks "Save all confirmed changes"
Then: "Plasma" row shows use_quant = TRUE

Test: Unsaved changes warning on close

Given: User has toggled use_quant for "Plasma" but not saved
When: User attempts to close the edit panel
Then: Warning dialog appears with Save, Discard, and Cancel options

Test: REQ-SPECIMEN-005​

Back to requirement

Test: Delete specimen with associations shows warning

Given: Specimen "Serum" has a suffix mapping association
When: User initiates deletion of "Serum"
Then: Warning is displayed indicating existing associations
When: User confirms deletion
Then: "Serum" is removed from the table

Test: REQ-SPECIMEN-006​

Back to requirement

Test: Link visible when specimen source is "From Target Suffix"

Given: User logged in as SUPER_ADMIN in Config Mode
And: use_sample_type is set to "From Target Suffix"
When: User hovers over "Other Settings"
Then: "Target Name Suffix to Specimen" link is visible

Test: Link hidden when specimen source is not "From Target Suffix"

Given: User logged in as SUPER_ADMIN in Config Mode
And: use_sample_type is not set to "From Target Suffix"
When: User hovers over "Other Settings"
Then: "Target Name Suffix to Specimen" link is not visible

Test: REQ-SPECIMEN-007​

Back to requirement

Test: Display suffix mappings

Given: Site has suffix mappings: "NPS" -> "Nasopharyngeal Swab", "PL" -> "Plasma"
When: User navigates to the Target Suffix page
Then: Table displays:
  | Target Name Suffix | Specimen Name         | Actions |
  | NPS                | Nasopharyngeal Swab   | Delete  |
  | PL                 | Plasma                | Delete  |

Test: Empty state

Given: Site has no suffix mappings
When: User navigates to the Target Suffix page
Then: "No records available" message is displayed

Test: REQ-SPECIMEN-008​

Back to requirement

Test: Add mapping with existing specimen

Given: Specimen "Plasma" exists for the site
When: User clicks "Add" on the Target Suffix page
And: User selects "Plasma" from the Specimen dropdown
And: User enters suffix "pl"
And: User clicks "Add Mapping"
Then: Mapping is created with suffix stored as "PL"
And: Table refreshes showing the new mapping

Test: Reject duplicate suffix (case-insensitive)

Given: Suffix "NPS" already exists
When: User tries to add suffix "nps"
Then: Validation error "Suffix should be unique (case-insensitive)" is displayed

Test: Inline specimen creation

Given: User is on the add mapping form
When: User clicks the inline "Add" button to create a new specimen
And: User enters specimen name "CSF" and saves
Then: "CSF" appears in the Specimen dropdown for selection

Test: REQ-SPECIMEN-009​

Back to requirement

Test: Edit mapping specimen selection

Given: Mapping "NPS" -> "Nasopharyngeal Swab" exists
When: User clicks the "NPS" row
Then: Edit panel opens with suffix "NPS" as disabled field
And: Specimen dropdown shows "Nasopharyngeal Swab" selected
When: User changes specimen to "Plasma" and clicks "Confirm Changes"
And: User clicks "Save"
Then: "NPS" row now shows "Plasma" as specimen

Test: REQ-SPECIMEN-010​

Back to requirement

Test: Delete mapping with confirmation

Given: Mapping "NPS" -> "Nasopharyngeal Swab" exists
When: User clicks the delete button on the "NPS" row
Then: Confirmation dialog appears: "Are you sure you want to delete the mapping for suffix 'NPS'?"
When: User confirms deletion
Then: Mapping is removed and table refreshes

Test: Cancel deletion

Given: Mapping "NPS" -> "Nasopharyngeal Swab" exists
When: User clicks the delete button and then cancels the confirmation
Then: Mapping remains unchanged

Test: REQ-SPECIMEN-011​

Back to requirement

Test: Target name matches configured suffix

Given: Suffix mapping "NPS" -> "Nasopharyngeal Swab" is configured
And: A runfile contains a target named "HIV-NPS"
When: The runfile is imported
Then: Observations for target "HIV-NPS" are associated with specimen type "Nasopharyngeal Swab"

Test: No suffix match leaves specimen unassigned

Given: Suffix mapping "NPS" -> "Nasopharyngeal Swab" is configured
And: A runfile contains a target named "HIV-IC"
When: The runfile is imported
Then: No specimen type is assigned to target "HIV-IC"

Test: REQ-SPECIMEN-012​

Back to requirement

Test: Help toggle visibility

Given: help_items feature flag is enabled
When: User views the Target Suffix page
Then: Help data toggle is visible
When: User activates the toggle
Then: Contextual help information is displayed

Appendix: Process Artifacts​

Completion Checklist​

  • Statement section present (1-2 paragraphs)
  • Mermaid diagram present and renders without errors
  • Diagram marked as (Illustrative)
  • No "non-normative" text anywhere
  • All REQ-SPECIMEN-* IDs assigned (12 requirements)
  • All ACs preserved with blank lines before bullet lists
  • All Trace references preserved (Source, Jira, Tests)
  • Error handling documented
  • Config options have Affects column
  • Tests at end with back-links
  • UI Notes marked (Illustrative)
  • Implementation marked (Illustrative)
  • Appendix has Completion Checklist and Reviewer Notes

Reviewer Notes​

New Document (v3.1.0)

This document was created for v3.1.0 to capture the expanded specimen type management functionality introduced by BT-5894. The following decisions were made during authoring:

  1. New domain prefix REQ-SPECIMEN -- Chosen instead of extending REQ-KITCFG to address OQ-015 from the v3.1.0 requirements inventory (kitcfg.md expansion concern). Specimen management is functionally cohesive and benefits from a dedicated file.
  2. Relationship to REQ-KITCFG-031 -- The v3.0.0 REQ-KITCFG-031 (Manage Specimen Types) covers import-only specimen management via Excel. REQ-SPECIMEN-001 through REQ-SPECIMEN-005 supersede this with a full CRUD UI, the use_quant field, and Config Mode integration. The original REQ-KITCFG-031 should be reviewed for deprecation once v3.1.0 is finalized.
  3. Source material -- Requirements extracted from input/3.1.0-confluence-updates.md Tables 5 (Specimen Types, 10 rows) and 6 (Target Name Suffix to Specimen, 11 rows). Rows covering implementation detail (model migration, site scoping trait) were folded into ACs rather than promoted to standalone requirements.
  4. REQ-SPECIMEN-005 (Delete) -- The source material mentions delete capability implicitly through UI design. The requirement was included as a standalone REQ because deletion with association warnings is independently testable behavior.
  5. REQ-SPECIMEN-011 (Import matching) -- Derived from the overall BT-5894 feature description. The source tables focus on CRUD UI; the import integration is the core value proposition of the suffix-based workflow.