LoadHL7Files

Overview

LoadHL7FilesTask processes HL7 message files from a directory, parsing and importing patient demographics, visits, orders, and charges into database tables. The task reads all HL7 files from a specified folder, validates message types against an allowed list, extracts structured data, and archives processed files to a separate directory.

Use this task when: You need to import HL7 messages (ADT, SIU, ORM, DFT) from external systems like EMRs, practice management systems, or lab interfaces to populate patient, visit, order, and charge data.

Don't use this task when:

• Processing real-time HL7 messages via TCP/IP interfaces (use HL7 listener service instead)
• Working with non-HL7 data formats like CSV or delimited files (use LoadDataFileTask instead)
• Need to export HL7 messages (this task is import-only)

Parameters

Execution Flow

Processing Algorithm

The task processes HL7 files using a three-phase approach:

Phase 1: File Discovery and Reading

1. File Enumeration: Scans MessageFolderPath for all files, excluding .part extension (incomplete transfers)
2. Progress Logging: Logs progress every 10 files to track batch processing

Phase 2: Message Parsing and Validation

1. Read File: Extracts raw HL7 message text from file
2. Parse Message: Uses HL7Processor to parse message structure:
   • Validates MSH segment (message header) is present
   • Extracts message type from MSH-9 field (e.g., ADT^A01)
   • Checks if message type is in AllowedMessageTypes list
   • Parses all segments into structured data dictionary
3. Error Handling:
   • Missing MSH segment → Mark as Error, log "No MSH segment found"
   • Unknown message type → Mark as Error, log "Unknown message type"
   • Disallowed message type → Mark as Skip, log "Message type not allowed"
   • Incomplete required segments → Mark as Error with specific segment error

Phase 3: Database Import and Archiving

1. HL7Archive Table: Every message (including errors and skips) is saved with:

   • Unique archive key
   • Original message text
   • Error flag and error message (if applicable)
   • Skip flag (if message type not allowed)

2. HL7Message Table: Every message is saved with:

   • Parsed segment list (MSH, PID, PV1, etc.)
   • Message metadata

3. Type-Specific Table: For successfully parsed, allowed messages only:

   • ADT Messages (A01, A03, A04, A09, A10) → HL7ADT table
   • Patient Messages (A08, A28, A31) → HL7Patient table
   • Visit Messages (S12, S13, S14, S15, S17, S26) → HL7Visit table
   • Order Messages (O01) → HL7Order table
   • Charge Messages (P03) → HL7Charge table

4. File Archiving: Move processed file to MessageProcessedFolderPath:

   • Optionally append timestamp if AddTimestampToFileName = true
   • Organize into subdirectories by status (successful vs. error/skip)

Supported Message Types

Usage Examples

Example 1: Process all supported message types with archiving

var task = new LoadHL7FilesTask
{
    MessageFolderPath = @"C:\HL7\Incoming",
    MessageProcessedFolderPath = @"C:\HL7\Archive",
    // AllowedMessageTypes omitted - defaults to all 16 supported types
    // AddTimestampToFileName omitted - defaults to true
};

Example 2: Process only patient and visit messages

var task = new LoadHL7FilesTask
{
    MessageFolderPath = @"C:\HL7\Incoming",
    MessageProcessedFolderPath = @"C:\HL7\Archive",
    AllowedMessageTypes = new List<string>
    {
        "ADT^A08",  // Patient update
        "ADT^A28",  // Add patient
        "ADT^A31",  // Update patient
        "SIU^S12",  // Appointment notification
        "SIU^S13",  // Appointment rescheduling
        "SIU^S15"   // Appointment cancellation
    },
    AddTimestampToFileName = true
};

Example 3: Process only charge messages without timestamp

var task = new LoadHL7FilesTask
{
    MessageFolderPath = @"\\server\share\HL7\DFT",
    MessageProcessedFolderPath = @"\\server\share\HL7\Processed",
    AllowedMessageTypes = new List<string> { "DFT^P03" },
    AddTimestampToFileName = false // Use original filenames in archive
};

Example 4: Import from network share with full message type filtering

var task = new LoadHL7FilesTask
{
    MessageFolderPath = @"\\EMR-Server\HL7Export\Outbound",
    MessageProcessedFolderPath = @"\\EMR-Server\HL7Export\Archived",
    AllowedMessageTypes = new List<string>
    {
        // ADT messages
        "ADT^A01", "ADT^A03", "ADT^A04",
        // Patient updates
        "ADT^A08", "ADT^A28",
        // Orders
        "ORM^O01",
        // Charges
        "DFT^P03"
    },
    AddTimestampToFileName = true
};

Related Tasks Comparison

When to use LoadHL7FilesTask:

• Source data is HL7 v2.x format
• Need to import patient demographics, visits, orders, or charges from EMR/PM systems
• Processing batch HL7 feeds from interfaces
• Want automatic file archiving by processing status

When to use alternatives:

• Non-HL7 format data → Use LoadDataFileTask or ProcessDataFileTask
• Real-time HL7 messages → Use HL7 listener service
• Custom data transformations → Use ProcessDataFileTask with custom mappings

Performance Considerations

Database Impact

• Connection Usage: Single connection maintained throughout task execution
• Tables Affected: Up to 7 tables per message:
  • HL7Archive (always)
  • HL7Message (always)
  • One of: HL7ADT, HL7Patient, HL7Visit, HL7Order, or HL7Charge (if valid message)
• Transaction Scope: Each file is saved independently (failure of one file doesn't affect others)
• Bulk Operations: Individual row inserts per message (not bulk copy)
• Locking: Row-level locks during insert; minimal blocking

File System Impact

• I/O Pattern: Sequential read of each file, then move operation
• File Locking: Files must not be locked by other processes
• Network Shares: Task supports UNC paths but performance depends on network latency
• Partial Files: Files ending in .part are automatically excluded to avoid processing incomplete transfers

Optimization Tips