SendHL7Letters

Overview

SendHL7LettersTask sends pending HL7 outbound messages by generating PDF files from patient letters and writing both the PDF and HL7 message text to disk. The task retrieves all unsent HL7 outbound letters from the database, formats them with timestamp and file path information, generates PDF attachments, and marks the letters as sent.

Use this task when: You need to export patient letters as HL7 ORU^R01 messages with PDF attachments for transmission to external systems (labs, EMRs, billing systems, etc.) via file-based integration.

Don't use this task when:

Sending patient letters via email or SMS (use AutoSendLettersTask instead)
Importing HL7 messages from external systems (use LoadHL7FilesTask instead)
No HL7 outbound letters exist in the database (letters must be created first, typically by AutoSendLettersTask)

Parameters

Parameter	Type	Required	Default	Description
`OutputFilePath`	`string`	Yes	`"C:\\HL7"`	Local directory path where both HL7 message (.txt) and PDF files will be written
`PublishDirectory`	`string`	Yes	`"C:\\HL7"`	Directory path referenced in the HL7 message OBX segment (where receiving system should find the PDF)
`SendingApplication`	`string`	Yes	`"MDClarity"`	HL7 MSH-3: Sending Application identifier
`SendingFacility`	`string`	Yes	`"MDClarity"`	HL7 MSH-4: Sending Facility identifier
`ReceivingApplication`	`string`	Yes	`"MDClarity"`	HL7 MSH-5: Receiving Application identifier (target system)
`ReceivingFacility`	`string`	Yes	`"MDClarity"`	HL7 MSH-6: Receiving Facility identifier (target location)
`ProcessingID`	`string`	Yes	`"P"`	HL7 MSH-11: Processing ID ("P" = Production, "T" = Test, "D" = Debug)
`VersionID`	`string`	Yes	`"2.5"`	HL7 MSH-12: HL7 version (typically "2.3", "2.4", "2.5", or "2.6")

Important: All parameters are required. The task validates that no property is empty and will throw an exception if any are missing.

Execution Flow

Processing Algorithm

The task processes each unsent letter through the following steps:

Letter Retrieval: Queries HL7OutboundLetter table for all records where SentDate IS NULL
PDF Generation: For each letter, retrieves the PatientLetter.Html and generates a PDF file
Message Formatting: Replaces placeholders in the HL7 message template:
- {FilePath} → Escaped path to PDF (e.g., D:\\HL7\\PatientLetter_HG-123_[id].pdf)
- {MessageTime} → HL7 formatted timestamp (e.g., [id])
- {MessageID} → Letter key (e.g., HG-123)
- {SendingApplication}, {SendingFacility}, etc. → Values from Properties
File Writing: Writes two files per letter:
- HL7 message text file: HL7Message_{Key}_{Timestamp}.txt
- PDF attachment: PatientLetter_{Key}_{Timestamp}.pdf
Status Update: Sets SentDate and FileLocation on HL7OutboundLetter and saves to database

Example Execution

Scenario: Processing 3 pending HL7 outbound letters at 2025-01-28 12:00:00

Input:

3 HL7OutboundLetter records with SentDate = NULL, PatientLetterKeys = L-001, L-002, L-003
PatientLetter HTML content in database for each key
OutputFilePath = C:\HL7Output
PublishDirectory = D:\HL7Publish

Execution Steps:

Validate all 8 Properties are non-empty ✓
Retrieve 3 unsent letters from database
For letter HG-001:
- Get PatientLetter L-001 HTML: <html><body>Your estimate is $150...</body></html>
- Generate PDF → Save to C:\HL7Output\PatientLetter_HG-001_[id].pdf
- Format message: Replace {FilePath} with D:\\HL7Publish\\PatientLetter_HG-001_[id].pdf
- Format message: Replace {MessageTime} with [id]
- Format message: Replace {MessageID} with HG-001
- Format message: Replace header fields with Properties values
- Write HL7 message → Save to C:\HL7Output\HL7Message_HG-001_[id].txt
- Update HL7OutboundLetter: SentDate = 2025-01-28 12:00:00, FileLocation = C:\HL7Output
Repeat for HG-002 and HG-003
Complete

Output:

6 files written to C:\HL7Output:
- HL7Message_HG-001_[id].txt
- PatientLetter_HG-001_[id].pdf
- HL7Message_HG-002_[id].txt
- PatientLetter_HG-002_[id].pdf
- HL7Message_HG-003_[id].txt
- PatientLetter_HG-003_[id].pdf
3 HL7OutboundLetter records updated with SentDate and FileLocation

Usage Examples

Example 1: Basic production HL7 output

var task = new SendHL7LettersTask
{
    Properties = new HL7SendProperties
    {
        OutputFilePath = @"C:\HL7Output",
        PublishDirectory = @"D:\HL7Publish",  // May be different if files are moved after creation
        SendingApplication = "MDClarity",
        SendingFacility = "MDClarityHospital",
        ReceivingApplication = "LabSystem",
        ReceivingFacility = "LabCorp",
        ProcessingID = "P",  // Production
        VersionID = "2.5"
    }
};

Example 2: Test environment with debug processing

// Send HL7 messages in test mode with debug processing ID
var task = new SendHL7LettersTask
{
    Properties = new HL7SendProperties
    {
        OutputFilePath = @"C:\TestHL7",
        PublishDirectory = @"C:\TestHL7",  // Same directory for test
        SendingApplication = "MDClarity_Test",
        SendingFacility = "TestFacility",
        ReceivingApplication = "TestEMR",
        ReceivingFacility = "TestSite",
        ProcessingID = "D",  // Debug mode
        VersionID = "2.5"
    }
};

Example 3: Integration with EMR using HL7 2.3

// Send patient letters to EMR that only supports HL7 v2.3
var task = new SendHL7LettersTask
{
    Properties = new HL7SendProperties
    {
        OutputFilePath = @"\\NetworkShare\HL7\Outbound",  // Network share monitored by EMR
        PublishDirectory = @"\\NetworkShare\HL7\PDF",
        SendingApplication = "MDCLARITY",
        SendingFacility = "HOSPITAL1",
        ReceivingApplication = "EPICEMR",  // Target EMR system
        ReceivingFacility = "MAINSITE",
        ProcessingID = "P",
        VersionID = "2.3"  // Older HL7 version for compatibility
    }
};

Example 4: Part of a patient letter pipeline

// Step 1: Generate patient letters (creates HL7OutboundLetter records)
var autoSendTask = new AutoSendLettersTask();
autoSendTask.Execute(dataStore);

// Step 2: Send HL7 messages with PDF attachments to external system
var sendHL7Task = new SendHL7LettersTask
{
    Properties = new HL7SendProperties
    {
        OutputFilePath = @"C:\HL7\Outbound",
        PublishDirectory = @"C:\HL7\PDF",
        SendingApplication = "MDClarity",
        SendingFacility = "Facility001",
        ReceivingApplication = "BillingSystem",
        ReceivingFacility = "BillingSite",
        ProcessingID = "P",
        VersionID = "2.5"
    }
};
sendHL7Task.Execute(dataStore);

// Step 3: Upload HL7 files to remote SFTP server
var uploadTask = new UploadTask
{
    LocalDirectory = @"C:\HL7\Outbound",
    RemoteDirectory = "/inbound/hl7",
    // ... other upload properties
};
uploadTask.Execute(dataStore);

Related Tasks Comparison

Task	Use Case	Direction	Message Type	File Generation
SendHL7LettersTask	Export patient letters as HL7 messages	Outbound (MDClarity → External)	ORU^R01 (with PDF)	Generates both .txt and .pdf files
`LoadHL7FilesTask`	Import patient data from HL7 feeds	Inbound (External → MDClarity)	ADT, ORM, DFT, etc.	Reads existing HL7 files
`AutoSendLettersTask`	Send patient letters via email/SMS	Outbound (MDClarity → Patients)	Email/SMS	Creates HL7OutboundLetter records (used by SendHL7LettersTask)
`Upload`	Transfer files to remote servers	Outbound (Local → Remote)	Any file type	No file generation (transfers existing files)

Key Differences:

SendHL7LettersTask generates both HL7 message files and PDF attachments for file-based integration
LoadHL7FilesTask is the inverse operation: imports HL7 data from external systems
AutoSendLettersTask creates the HL7OutboundLetter records that SendHL7LettersTask processes
SendHL7LettersTask typically runs after AutoSendLettersTask in a pipeline
Upload is often used after SendHL7LettersTask to transfer generated files to remote systems

Typical Pipeline:

AutoSendLettersTask → SendHL7LettersTask → Upload (to SFTP/FTP)

Performance Considerations

Database Impact

Tables Read:
- HL7OutboundLetter: Query for unsent letters (WHERE SentDate IS NULL)
- PatientLetter: One read per unsent letter to retrieve HTML content
Tables Written:
- HL7OutboundLetter: Updates SentDate and FileLocation for each processed letter (one UPDATE per letter)
Query Pattern: Simple indexed queries (one SELECT for all unsent letters, individual SELECTs for PatientLetter by key)

File System Impact

Files Created: 2 files per letter (1 .txt HL7 message + 1 .pdf attachment)
File Naming: HL7Message_{Key}_{Timestamp}.txt and PatientLetter_{Key}_{Timestamp}.pdf
Disk Space: PDF size varies by letter content (typically 50KB - 500KB per PDF)
Directory Access: Requires write permissions to OutputFilePath

Optimization Tips

Scenario	Recommendation	Rationale
High volume (1000s of letters)	Run during off-hours; ensure adequate disk space	PDF generation can be CPU-intensive and files consume disk space
Network share output	Use local path then transfer via Upload task	Direct network writes are slower; local-then-upload is faster
Frequent small batches	Run every 5-15 minutes	Reduces latency for letter delivery to external systems
Large letter HTML	Monitor PDF generation time	Complex HTML with images can take 1-5 seconds per PDF