Business Flows

This document outlines the detailed business logic and workflow processes for the MS Word Integration feature, covering session management, file processing, and error handling.

Primary User Workflow

1. Session Initiation

Trigger: User clicks "Edit in Microsoft Word" button in Operations Waiting List

Business Logic:

1. Validate user permissions for the lab report
2. Check if an active session already exists
3. If existing session found:
   • If user is the author: Allow continuation
   • If different author: Offer "Take Authorship" option
   • If session expired: Create new session
4. Retrieve selected template configuration
5. Generate unique session token
6. Create ExternalReportEdits record with is_active = 1
7. Fetch patient and test data for placeholder replacement
8. Process template with placeholder substitution
9. Generate presigned S3 URL for template download
10. Return session data to frontend

Edge Cases:

• Template not found: Return error with available templates
• Concurrent session conflict: Handle authorship transfer
• Network timeout: Retry with exponential backoff

2. External Editing Session

Trigger: Microsoft Word opens with the processed template

Business Logic:

1. Word application launches via winword: protocol
2. User edits document with full Word functionality
3. On first save, Word uploads files to the configured endpoint
4. Backend validates uploaded files
5. Store files in S3 with proper naming convention
6. Update ExternalReportEdits record with file paths
7. Mark lab report as partially completed (isPartialFill = 1)
8. Send real-time notifications to waiting list

Session Management:

• Timeout: 2 hours of inactivity
• Auto-save: Files uploaded on each save operation
• Conflict Resolution: Last save wins, with timestamp tracking

3. Session Completion

Trigger: User explicitly ends session or timeout occurs

Business Logic:

1. Set is_active = 0 on ExternalReportEdits record
2. Update updated_at timestamp
3. Clean up temporary files if any
4. Log session completion for audit trail
5. Notify other users that session is available

Template Processing Flow

Placeholder Replacement Logic

Data Sources:

• Patient Data: From userDetails table
• Test Data: From allTests and report_results tables
• Lab Data: From labs table
• Dynamic Data: Current timestamp, calculated fields

Replacement Rules:

• Use regex pattern: {{\s*(\w+)\s*}}
• Case-sensitive matching
• Empty string for missing data
• No HTML escaping (Word document context)

Template Validation

Pre-processing Checks:

1. File exists in S3
2. File is valid DOCX format
3. File size within limits
4. Contains at least one placeholder (optional)

Post-processing Validation:

1. Output file is valid DOCX
2. All placeholders processed
3. File size reasonable
4. No corruption during processing

File Upload and Storage Flow

Upload Processing

File Naming Convention:

{patient_name}_{timestamp}_{file_type}.{extension}

S3 Path Structure:

ExternalReportEdit/{patient_id}/{filename}

PDF Conversion

Trigger: Word document uploaded successfully

Process:

1. Download Word document from S3
2. Use Word automation or third-party service to convert to PDF
3. Upload PDF to S3
4. Update database with PDF path
5. Clean up temporary files

Fallback: If conversion fails, store Word document as primary artifact

Error Handling and Recovery

Session Recovery

Scenario: User loses connection during editing

Recovery Logic:

1. Session remains active for 2 hours
2. User can reconnect using same session token
3. Files are preserved in S3
4. Authorship maintained

File Upload Failures

Scenario: Upload fails due to network issues

Recovery Logic:

1. Retry upload with exponential backoff
2. Store partial uploads for manual recovery
3. Notify user of failure with retry option
4. Maintain session state for continuation

Data Consistency

Scenario: Database update fails after file upload

Recovery Logic:

1. Use database transactions for atomicity
2. Implement cleanup jobs for orphaned files
3. Audit trail for manual reconciliation
4. Alert system administrators for critical failures

Security and Compliance

Authentication Flow

Audit Trail

Tracked Events:

• Session creation (user, timestamp, template)
• File uploads (filename, size, timestamp)
• Session termination (reason, duration)
• Authorship changes (old user, new user, timestamp)
• Error events (type, details, user impact)

Data Privacy

• Patient data encrypted in transit and at rest
• File access restricted to authorized lab users
• Automatic cleanup of temporary files
• Compliance with HIPAA/PHI regulations

Performance Considerations

Optimization Strategies

• Caching: Template metadata cached for 1 hour
• Streaming: Large file processing uses streaming to avoid memory issues
• Async Processing: File uploads processed asynchronously
• CDN: Use CloudFront for faster file downloads

Monitoring Metrics

• Session creation success rate
• Average session duration
• File upload success rate
• Template processing time
• Storage utilization

Integration Points

With Lab Report System

• Status Updates: Mark reports as partially completed
• Result Integration: Pull data from report_results table
• Workflow Integration: Seamless operation from waiting list

With Template Management

• Template Selection: Integration with template library
• Version Control: Track template versions used
• Usage Analytics: Report on template popularity

With User Management

• Permission Checks: Validate user access to specific reports
• Role-based Access: Different permissions for different user types
• Audit Logging: Track all user actions for compliance