Upload Runs
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Importing run files from thermocycler instruments into the system Domain: UPLOAD
Statement
The system shall accept run file uploads from authorized users, validate file types against supported formats, and process files for import into the runfile list.
Upload operations include real-time progress monitoring, duplicate detection, error handling with failure reasons, upload cancellation, and bulk file processing. Users can navigate to successfully imported files via the Runfile Report. Role restrictions determine which users may perform uploads, and client configuration determines which file formats are accepted.
Behavior Overview (Illustrative)
This diagram illustrates the high-level behavior. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Run File | A data file exported from a thermocycler instrument containing well and assay data |
| Duplicate File | A run file that has already been imported to the system, identified by content matching |
| Bulk Upload | Simultaneous upload of multiple files in a single user action |
Assumptions
SME confirmed 2026-01-20.
- Users accessing upload functionality have appropriate role permissions (role-based access)
- The external Parser API handles all supported file formats (format support is determined by the parser, not client configuration)
- Network connectivity is available for file transfer operations
Functional Requirements
File Upload (REQ-UPLOAD-001)
FR-UPLOAD-001 Accept Run File Uploads
The system shall accept run file uploads from authorized users.
Acceptance Criteria:
Upload Capability:
- The system shall accept file uploads initiated by the user
- The system shall provide confirmation when upload begins
- The system shall provide confirmation when upload completes successfully
Role Restrictions:
- The system shall restrict upload capability to Junior User, Senior User, and Super-Admin roles
- The system shall reject upload attempts from Client-Admin and Manager roles
Upload Methods:
- The system shall accept uploads from any screen in the application via drag-and-drop method
- The system shall accept uploads via dedicated Import Files function
Error Handling
- Unauthorized role attempts upload: The system shall reject the upload and display an error message
Trace: Source: 3.0.0-Upload Runs (Rows 1, 2, 3, 12) | Jira: BT-995, BT-830, BT-3035 | Tests: BT-831
File Validation (REQ-UPLOAD-002)
FR-UPLOAD-002 Validate Uploaded File Types
The system shall validate that uploaded files are of supported types before processing.
Acceptance Criteria:
Validation Logic:
- The system shall detect file type before processing
- The system shall accept files matching configured supported formats
- The system shall reject files not matching configured supported formats
- The system shall provide error feedback for rejected files
Format Support:
- The system shall support .sds, .pcrd, and .eds file formats per client configuration
- The system shall determine file format support based on Client Configuration
Error Handling
- Invalid file type: The system shall reject the file and display an error message
Trace: Source: 3.0.0-Upload Runs (Rows 2, 8, 9, 10) | Jira: BT-995, BT-830, BT-1947, BT-2548 | Tests: BT-2574
Upload Monitoring (REQ-UPLOAD-003)
FR-UPLOAD-003 Display Upload Progress
The system shall display upload progress to users during file upload operations.
Acceptance Criteria:
Progress Display:
- The system shall display upload progress as a percentage
- The system shall update progress in real-time during upload
- The system shall indicate upload status (in progress, complete, error)
Timestamp Display:
- The system shall display upload timestamp for completed uploads
- The system shall display upload timestamps in DD-MMM-YY format
Trace: Source: 3.0.0-Upload Runs (Rows 4, 11) | Jira: BT-995, BT-3019 | Tests: [Pending]
Post-Upload Navigation (REQ-UPLOAD-004)
FR-UPLOAD-004 Navigate to Uploaded File
The system shall allow users to navigate to successfully uploaded files for viewing.
Acceptance Criteria:
- The system shall provide navigation to view successfully uploaded files
- Navigation shall be available only for files that completed upload successfully
- Navigation shall direct users to the Runfile Report for the selected file
Trace: Source: 3.0.0-Upload Runs (Row 5) | Jira: BT-995 | Tests: [Pending]
Error Display (REQ-UPLOAD-005)
FR-UPLOAD-005 Display Upload Errors
The system shall display error information when file uploads fail.
Acceptance Criteria:
Error Indication:
- The system shall indicate when an upload has failed
- The system shall provide reason for upload failure
- Failed uploads shall not appear in the Run Files list
Duplicate Detection:
- The system shall identify duplicate file uploads
- The system shall detect duplicate files at approximately 20% of upload progress
Navigation Restriction:
- The system shall prevent navigation to files with errors
Error Handling
- Duplicate file detected: The system shall stop the upload and mark the file as duplicate
- Missing configuration: The system shall indicate the specific missing configuration causing failure
Trace: Source: 3.0.0-Upload Runs (Row 6), 3.0.0-Add Import Failure Message to Run Import Progress Status Tooltip (Row 1) | Jira: BT-995, BT-4598 | Tests: BT-4600
Upload Control (REQ-UPLOAD-006)
FR-UPLOAD-006 Cancel Upload in Progress
The system shall allow users to cancel file uploads while in progress.
Acceptance Criteria:
- The system shall allow cancellation while upload is in progress
- Cancellation shall stop the upload immediately
- Cancelled files shall not be imported to the system
- Cancelled files shall be removed from the upload display
Trace: Source: 3.0.0-Upload Runs (Row 7) | Jira: BT-995 | Tests: [Pending]
Bulk Upload (REQ-UPLOAD-007)
FR-UPLOAD-007 Handle Bulk Uploads
The system shall process multiple files uploaded simultaneously, handling valid and invalid files appropriately.
Acceptance Criteria:
Processing Logic:
- The system shall process each file in a bulk upload independently
- Valid files shall be imported regardless of invalid files in the same batch
User Notification:
- The system shall notify users when some files are ignored
- The system shall notify users when all files are invalid
- The system shall confirm success when all files are valid
Error Handling
- Some files invalid: The system shall import valid files and display warning with list of ignored files
- All files invalid: The system shall reject the upload and display error message
Trace: Source: 3.0.0-Import - Add Warning for Ignored File (Row 1) | Jira: BT-3983 | Tests: BT-831
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
| supported_file_formats | .sds, .pcrd, .eds | File extensions accepted for upload | REQ-UPLOAD-002 |
| upload_date_format | DD-MMM-YY | Display format for upload timestamps | REQ-UPLOAD-003 |
UI Notes (Illustrative)
FR-UPLOAD-001 UI Specifications
Upload Methods:
- Drag and drop: Available from any screen, system detects file being dragged and displays prompt
- File dialog: "Import files" button opens standard file selection dialog
Toast Notifications:
- Upload initiated: Yellow toast - "Wait...Your uploads are being prepared."
- Upload complete: Green toast - "Great...Your file(s) have been uploaded."
- Invalid files: Red toast - "Oops...Invalid files."
Visual Elements:
- Upload files modal appears after successful upload
- See: media/image121.png (Drag and drop prompt)
- See: media/image122.png (Invalid file error display)
FR-UPLOAD-002 UI Specifications
Error Display:
- Red toast notification for invalid files
- Same error displayed when restricted user types attempt upload
FR-UPLOAD-003 UI Specifications
Progress Table:
- Row background colors indicate status:
- Grey: uploading/converting (20-30%)
- Green: imported successfully (100%)
- Red: error
- "Uploaded At" column displays date
Visual Elements:
- See: media/image123.png (Upload progress display)
FR-UPLOAD-004 UI Specifications
Navigation:
- "Open file" button displayed in last column
- Available on Upload Runs page and Upload files modal
- Button only shown when upload reaches 100%
Visual Elements:
- See: media/image124.png (Open file button)
FR-UPLOAD-005 UI Specifications
Error Display:
- Error rows displayed with red background
- Open file icon hidden for error rows
- Tooltip shows import failure reason when hovering over status
Visual Elements:
- See: media/image125.png (Error display with red background)
FR-UPLOAD-006 UI Specifications
Cancel Control:
- Cancel upload button available in last column during upload
- Button available while status is Uploaded/Converting (20-30%)
FR-UPLOAD-007 UI Specifications
Notification Messages:
- Partial success: "Some files are ignored" with list of filenames
- All invalid: "Import Failed - Unsupported files."
- All valid: Success message
General UI Patterns
- Toast notification pattern for upload status feedback
- Color-coded row backgrounds: grey (in progress), green (success), red (error)
- Modal dialog for upload files interface
- Tooltip for detailed error information
Implementation (Illustrative)
| Component | Type | Path | Requirements |
|---|---|---|---|
| RunFilesController@store | Controller | App\Http\Controllers\RunFilesController | REQ-UPLOAD-001, REQ-UPLOAD-002 |
| RunFilesController@destroy | Controller | App\Http\Controllers\RunFilesController | REQ-UPLOAD-006 |
| FailedRunFilesController@destroy | Controller | App\Http\Controllers\FailedRunFilesController | REQ-UPLOAD-005 |
| StoreRunFilesAction | Action | App\Actions\RunFiles\StoreRunFilesAction | REQ-UPLOAD-001, REQ-UPLOAD-007 |
| DispatchNextFileToParsingAction | Action | App\Actions\RunFiles\DispatchNextFileToParsingAction | REQ-UPLOAD-002 |
| RetryFailedRunfilesAction | Action | App\Actions\RunFiles\RetryFailedRunfilesAction | REQ-UPLOAD-005 |
| RunFileImportProgressBroadcast | Event | App\Events\RunFileImportProgressBroadcast | REQ-UPLOAD-003 |
| RunFileImportProgress | Model | App\RunFileImportProgress | REQ-UPLOAD-003, REQ-UPLOAD-005 |
Implementation (Frontend)
| Component Type | Location | Requirements |
|---|---|---|
| View | views/UploadRunFiles.vue | REQ-UPLOAD-001, REQ-UPLOAD-003, REQ-UPLOAD-004, REQ-UPLOAD-006 |
| View | views/LimsExport.vue | REQ-UPLOAD-001 |
| Components | components/lims-export/ | REQ-UPLOAD-003, REQ-UPLOAD-005 |
| Mixin | mixins/UploadRunFiles.js | REQ-UPLOAD-001, REQ-UPLOAD-007 |
| Store | store/modules/runs.js | REQ-UPLOAD-001, REQ-UPLOAD-003 |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-UPLOAD-001 | Accept Run File Uploads | Test | RunFilesController@store, StoreRunFilesAction | BT-831 | Draft |
| REQ-UPLOAD-002 | Validate Uploaded File Types | Test | RunFilesController@store, DispatchNextFileToParsingAction | BT-2574 | Draft |
| REQ-UPLOAD-003 | Display Upload Progress | Test | RunFileImportProgressBroadcast, RunFileImportProgress | [Pending] | Draft |
| REQ-UPLOAD-004 | Navigate to Uploaded File | Test | Frontend (UploadRunFiles.vue) | [Pending] | Draft |
| REQ-UPLOAD-005 | Display Upload Errors | Test | FailedRunFilesController, RunFileImportProgress | BT-4600 | Draft |
| REQ-UPLOAD-006 | Cancel Upload in Progress | Test | RunFilesController@destroy | [Pending] | Draft |
| REQ-UPLOAD-007 | Handle Bulk Uploads | Test | StoreRunFilesAction | BT-831 | Draft |
Notes
- Role restrictions apply across all upload methods (drag-and-drop and file dialog)
- Supported file formats may vary by client configuration
- Upload progress display is specific to the Upload Runs page interface
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| - | No open questions | - | - | - |
Acceptance Tests
Test: REQ-UPLOAD-001
Test: Authorized user upload succeeds
Given: User is logged in as Super-admin, Junior, or Senior user
When: User initiates file upload with a valid run file
Then: The system shall accept the upload
And: The system shall provide upload confirmation
And: The run file shall be imported
Test: Unauthorized role rejection
Given: User is logged in as Client-Admin or Manager
When: User attempts to upload a run file
Then: The system shall reject the upload
And: The system shall display an error message
And: The file shall not be imported
Test: REQ-UPLOAD-002
Test: Invalid file type rejection
Given: User attempts to upload an unsupported file type
When: File upload is initiated
Then: The system shall reject the file
And: The system shall display an error message
And: The file shall not be imported
Test: Supported file format - SDS
Given: Client Configuration allows .sds format files
When: Authorized user uploads file with .sds extension
Then: The system shall accept the file
And: The run shall be uploaded
Test: Supported file format - PCRD
Given: Client Configuration allows .pcrd format files
When: Authorized user uploads file with .pcrd extension
Then: The system shall accept the file
And: The run shall be uploaded
Test: Supported file format - EDS
Given: Client Configuration allows .eds format files
When: Authorized user uploads file with .eds extension
Then: The system shall accept the file
And: The run shall be uploaded
Test: REQ-UPLOAD-003
Test: Progress display during upload
Given: User has initiated a file upload
When: Upload is in progress
Then: The system shall display upload progress as percentage
And: Progress shall update in real-time
And: Upload status shall be indicated
Test: Upload timestamp display
Given: User views upload history
When: Observing completed uploads
Then: The system shall display upload timestamp
And: Timestamp format shall be DD-MMM-YY
Test: REQ-UPLOAD-004
Test: Open file after successful upload
Given: Run file has been successfully uploaded (100% complete)
When: User selects option to open the file
Then: The system shall navigate to the Runfile Report page
And: The uploaded run file shall be displayed
Test: REQ-UPLOAD-005
Test: Duplicate file detection
Given: A run file has already been imported
When: User attempts to import the same run file again
Then: The system shall detect the duplicate
And: Upload shall stop
And: File shall be marked with duplicate status
And: File shall not appear in Run Files list
And: Navigation to file shall be prevented
Test: Failure reason display
Given: Configuration has missing required element
And: Upload triggers processing requiring that element
When: User imports the run file
Then: The system shall indicate failure
And: Failure reason shall be available
Test: REQ-UPLOAD-006
Test: Cancel upload
Given: Run file upload is in progress
When: User requests to cancel the upload
Then: The system shall stop the upload immediately
And: The file shall not be imported
And: The file shall be removed from upload display
Test: REQ-UPLOAD-007
Test: All valid files in bulk upload
Given: Multiple files of supported format
When: User uploads all files simultaneously
Then: The system shall import all files
And: The system shall display success message
Test: All invalid files in bulk upload
Given: Multiple files of unsupported format
When: User uploads all files simultaneously
Then: The system shall reject all files
And: The system shall display error message
And: No files shall be imported
Test: Mixed valid and invalid files
Given: Mix of supported and unsupported file formats
When: User uploads all files simultaneously
Then: The system shall import valid files
And: The system shall reject invalid files
And: The system shall display warning with list of ignored files
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Run Import Process, Run Import explanations and Validate Run file |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion)
- UI details are fully demoted to Illustrative section
- Configuration options are not encoded as requirements
- Acceptance criteria describe behavior, not UI mechanics
- Every requirement has acceptance criteria and source traceability
- Error handling addressed for I/O, validation, and external system requirements
- Open questions documented with owners assigned
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- Refinements folded into Acceptance Criteria
- Traceability matrix is complete
Reviewer Notes
Consolidation: REQ-UPLOAD-001
The following items from the source were consolidated into a single capability-level requirement:
| Original Item | Source Reference | Disposition |
|---|---|---|
| REQ-UPLOAD-001 (Drag and drop) | 3.0.0-Upload Runs (Rows 1, 2, 12) | Merged -> REQ-UPLOAD-001 |
| REQ-UPLOAD-002 (File dialog) | 3.0.0-Upload Runs (Row 3) | Merged -> REQ-UPLOAD-001, AC-07 |
Rationale: Both original requirements describe the same system capability (accepting file uploads) with different interaction methods. The distinction between drag-and-drop and file dialog is a UI mechanic, not a distinct system responsibility. The consolidated requirement focuses on the capability of accepting uploads from authorized users, while the interaction methods are preserved as acceptance criteria.
Reversibility: To restore original structure, reference:
- Source:
output/pilot/restructured/upload-runs.md - Confluence: 3.0.0-Upload Runs (Rows 1-3, 12)
ID Renumbering
Due to consolidation, requirement IDs were renumbered:
| Original ID | New ID | Notes |
|---|---|---|
| REQ-UPLOAD-001 | REQ-UPLOAD-001 | Consolidated with UPLOAD-002 |
| REQ-UPLOAD-002 | (consolidated) | Merged into REQ-UPLOAD-001 |
| REQ-UPLOAD-003 | REQ-UPLOAD-002 | File validation |
| REQ-UPLOAD-004 | REQ-UPLOAD-003 | Progress display |
| REQ-UPLOAD-005 | REQ-UPLOAD-004 | Open completed upload |
| REQ-UPLOAD-006 | REQ-UPLOAD-005 | Error display |
| REQ-UPLOAD-007 | REQ-UPLOAD-006 | Cancel upload |
| REQ-UPLOAD-008 | REQ-UPLOAD-007 | Bulk upload |
Refinements Folded into Acceptance Criteria
Former refinements have been incorporated as acceptance criteria:
| Original Refinement | Requirement | New AC ID |
|---|---|---|
| RF-01 (drag-and-drop availability) | REQ-UPLOAD-001 | AC-06 |
| RF-02 (Import Files function) | REQ-UPLOAD-001 | AC-07 |
| RF-01 (supported file formats) | REQ-UPLOAD-002 | AC-05 |
| RF-02 (Client Configuration) | REQ-UPLOAD-002 | AC-06 |
| RF-01 (timestamp format) | REQ-UPLOAD-003 | AC-05 |
| RF-01 (duplicate detection timing) | REQ-UPLOAD-005 | AC-06 |