HL7 Transport: Shared Folder / File-Drop

Shared folder (or file-drop) transport is a legacy asynchronous method for exchanging HL7 messages via a network file share—typically an SMB/CIFS share on Windows or an NFS mount on Unix. One system writes HL7 messages into files in a drop folder; another system polls that folder periodically, picks up the files, processes them, and optionally moves them to an archive or delete folder. Messages are sent in batches using HL7 v2 batch-envelope segments (FHS, BHS, MSH, BTS, FTS) to group multiple messages in a single file. This transport is slow, fragile, and lacks built-in acknowledgments, but it persists in healthcare integrations because it requires no network infrastructure beyond file sharing and is compatible with legacy systems.

What is shared folder / file-drop

Shared folder transport moves messages by writing them to files on a network-accessible file system (SMB/CIFS share, NFS mount, FTP directory, or even a local filesystem in a VM-shared folder). A sender writes a file containing one or more HL7 messages (often wrapped in HL7 v2 batch envelope segments); a receiver periodically scans the folder, finds new files, reads them, processes the messages, and—optionally—acknowledges by moving the file to an archive folder, writing a receipt file, or deleting it.

The transport is asynchronous: the sender does not wait for a response. File-drop works around network restrictions (e.g., when firewall rules forbid inbound connections) and tolerates intermittent connectivity (the file persists on disk until processed). However, it introduces operational challenges: no real-time acknowledgments, fragile polling logic, file locks, race conditions, and difficulty tracking which messages have been processed.

File-drop is commonly found in large healthcare organizations integrating legacy systems, batch billing workflows, and external partners (insurance companies, clearinghouses) that only support file exchange. It is rarely the first choice for new integrations but remains widespread in mature EHR ecosystems.

How it works

Sender workflow:

System A prepares one or more HL7 messages (e.g., ADT, ORM, ORU).
System A optionally wraps them in an HL7 v2 batch envelope (FHS, BHS, MSH, BTS, FTS segments).
System A writes the message(s) to a temporary file (e.g., MSG123.tmp) in the drop folder with write-exclusive access.
System A closes the temporary file and atomically renames it to the final name (e.g., MSG123.hl7 or MSG123.txt).
The file now resides in the drop folder, accessible to the receiver.

Receiver polling workflow:

System B runs a scheduled job (e.g., every 5 seconds, every minute) that scans the drop folder.
System B looks for files matching a pattern (e.g., *.hl7) or files modified after a high-water mark timestamp.
System B attempts to open each file; if it fails (file locked by sender), System B skips it (the sender is still writing).
System B reads the entire file into memory.
If the file contains batch envelope segments (FHS/BHS), System B parses the batch and extracts individual messages (MSH...MSA groups).
System B processes each message.
System B moves the file to an archive folder (e.g., archive/MSG123.hl7) or deletes it.
Optionally, System B writes a receipt file (e.g., MSG123.hl7.ack) indicating success or failure.

Sender System                                   Drop Folder                              Receiver System
     |                                               |                                         |
     |                                               |                                         |
     |-- Write MSG123.tmp (exclusive lock) ---->  |                                         |
     |     (HL7 message content)                   |                                         |
     |                                               |                                         |
     |-- Atomic rename MSG123.tmp → MSG123.hl7 --->  |                                         |
     |     (file now visible/unlocked)              |                                         |
     |                                               |                                         |
     |                                               |<-- Poll folder every 60 sec --------  |
     |                                               |                                         |
     |                                               |-- List: [MSG123.hl7] -------->  |
     |                                               |                                 |
     |                                               |<-- Open, read MSG123.hl7 ------  |
     |                                               |     (parse MSH, PID, ...)        |
     |                                               |                                 |
     |                                               |<-- Move to archive/ --------->  |
     |                                               |     or delete MSG123.hl7        |
     |                                               |                                 |
     |                                               |<-- Write receipt: -------->  |
     |                                               |     MSG123.hl7.ack             |
     |                                               |     (SUCCESS or FAILED)         |
     |                                               |                                 |

Batch file structure:

An HL7 v2 batch file contains:

FHS|^~&|SendingApp|SendingFacility|ReceivingApp|ReceivingFacility|20260701120000|BatchID123|P|2.5.1
  BHS|^~&|SendingApp|SendingFacility|ReceivingApp|ReceivingFacility|20260701120000|MessageSetID|P|2.5.1|1|2|N
    MSH|^~&|REGMGR|HOSPITAL|HL7RECV|HOSPITAL|20260701120000||ADT^A01^ADT_A01|MSG000123|P|2.5.1
    PID|1||MRN123456^^^HOSPITAL||Doe^Jane||19800615|F|...
    PV1|1|I|CARDIO^ICU^BED01|...
    MSA|AA|MSG000123|
  BTS|2
FTS|1|1

FHS (File Header Segment): One per batch file. Contains file-level metadata (sending app, facility, timestamp, batch ID).
BHS (Batch Header Segment): One per batch. Contains batch-level metadata and a count of messages.
MSH...MSA groups: Each message (ADT, ORM, etc.) followed by its associated segments (PID, PV1, etc.). The MSA segment (Message Acknowledgment) is typically placeholder in a batch file.
BTS (Batch Trailer Segment): One per batch. Contains a count of messages in the batch.
FTS (File Trailer Segment): One per file. Contains counts of batches and messages.

For single-message files, the batch envelope is often omitted, and the file contains just the MSH and its segments.

When to use it

File-drop is appropriate when:

No network connectivity: The receiver is behind a firewall that blocks inbound connections; file sharing (SMB/NFS) is the only option.
Scheduled batch processing: Messages are naturally grouped into daily, weekly, or monthly batches (e.g., billing runs, compliance exports).
Legacy system integration: The system only supports file-based interfaces and cannot be modified.
Asynchronous workflows: It is acceptable to process messages hours or days after they are sent.
Archive and compliance: File-based storage naturally provides an audit trail; files persist on disk, supporting legal holds and disaster recovery.
Partner integrations: External partners (insurance companies, government agencies) only accept file exchanges via SFTP, FTP, or SMB.

Avoid file-drop if:

Real-time processing required: Patient data must be available immediately (e.g., ER admission). File polling introduces unacceptable delays.
Interactive confirmation needed: The sender needs to know immediately whether the message was accepted or rejected. File-drop has no mechanism for real-time ACKs.
High-frequency messages: Polling every second for hundreds of messages per second will overwhelm disk I/O and introduce race conditions.
Small payload, low latency: REST/HTTPS is simpler and faster for small, urgent messages.

Configuration parameters

Parameter	Value	Notes
Protocol	SMB/CIFS, NFS, SFTP, or FTP	Windows file sharing uses SMB/CIFS (port 445). Unix uses NFS (port 2049). SFTP (port 22) and FTP (port 21) are alternatives.
Share path	`/hospital/hl7/drop` or `\FILESERVERHL7_Drop`	Network path to the shared folder. Must be readable and writable by both sender and receiver.
File naming	`MSG<timestamp>.<ext>` or `<facilityid>_<messageid>.<ext>`	Convention agreed between sender and receiver. Examples: `MSG20260701120000.hl7`, `HOSPITAL_ADT_001.txt`.
File extension	`.hl7`, `.txt`, `.msg`, or any convention	Identifies the message format. Use `.hl7` for HL7 v2 ER7 format.
Character encoding	UTF-8 or ASCII	HL7 v2 ER7 is typically ASCII (7-bit) or UTF-8. Declare in file metadata or agree beforehand.
Line endings	LF (Unix) or CRLF (Windows)	Windows typically uses CRLF; Unix uses LF. HL7 segments are separated by `r` or `rn` (segment delimiter, MSH-3).
Atomic write	Rename pattern or exclusive lock	Sender writes to a `.tmp` file, then atomically renames to `.hl7`. This prevents receiver from reading incomplete files.
Polling interval	5s, 30s, 60s, or longer	Frequency of receiver scans. Trade-off between latency and disk I/O. Default 60s is safe for most workflows.
Acknowledgment method	Receipt file (`.ack`), archive folder, or deletion	Receiver indicates success by writing `MSG123.hl7.ack`, moving file to `archive/`, or deleting. No standard; must be agreed.
Archive folder	`/hospital/hl7/archive` or `/hospital/hl7/processed`	Receiver moves processed files here for auditability. Retention: 90 days typical for compliance.
Error folder	`/hospital/hl7/error` or `/hospital/hl7/failed`	Receiver moves unparseable files here for investigation.
File permissions	Sender: 0644; Receiver: 0644 (read/write both)	Ensure both systems can read/write. Restrictive permissions cause lock-outs.
Timeout	File lock timeout 30–60 seconds	If sender's file lock persists >30s, assume sender crashed; receiver may skip (or retry later).
Batch envelope	FHS, BHS, BTS, FTS (optional)	Use batch segments if multiple messages per file; omit for single-message files.

Security

File system access control: The SMB/CIFS share or NFS mount should restrict access to authorized users/systems only. Use Windows NTFS ACLs (ALLOW READ/WRITE for sender and receiver, DENY for everyone else) or Unix file permissions (mode 700 for the drop folder, readable/writable only by the sender and receiver accounts).

Encryption in transit: SMB/CIFS supports SMB signing and encryption (SMB 3.0+). Use EnableSecureNegotiate and RequireSecuritySignature on Windows file servers to ensure encrypted, signed traffic. NFS over UDP is unencrypted; use NFS over TCP with Kerberos (krb5i) or TLS (NFS-over-TLS, draft standard) for security.

Audit logging: Enable file-share audit logging: log all read/write/delete operations with timestamps and user accounts. This creates an audit trail for compliance. Windows: enable Object Access auditing; NFS: enable server-side NFS audit logs.

Message content security: File-drop has no built-in encryption of the message itself. If PHI must be protected, encrypt the HL7 message before writing (PGP, AES) or use encrypted file shares (BitLocker, eCryptfs). Alternatively, redact or tokenize sensitive fields in the file and store the actual values in a separate encrypted database.

Deletion and retention: After successful processing, delete or archive the file. Avoid leaving processed files in the drop folder indefinitely; this creates confusion and audit complexity. Implement automatic cleanup: move to archive after 7 days, delete from archive after 90 days (tune to your compliance requirements).

Pros & cons

Pros:

Simple and reliable: File sharing is ubiquitous in enterprise networks. No custom protocols, no firewall rules needed (just standard file-share access).
Firewalls and NAT: Works through firewalls that block inbound connections. Sender and receiver need only read/write file-share access, which is usually allowed.
Asynchronous: Sender does not wait for receiver. Tolerates processing delays and intermittent downtime.
Audit trail: Files persist on disk. Easy to replay, archive, and investigate failures months later.
Batch processing: Multiple messages in one file reduce file-system overhead and align with batch workflows (e.g., daily uploads).
No special infrastructure: Only requires a file server; no web servers, API gateways, or middleware needed.

Cons:

No real-time acknowledgment: Sender does not know if the message was processed until manually checking the receipt file or archive folder.
Polling latency: Receiver scans every N seconds; messages are not processed until the next poll cycle. Real-time workflows suffer.
Race conditions and locks: If sender is still writing and receiver starts reading, the file may be corrupted or locked. Requires careful atomic-write logic (rename, exclusive locks).
Hard to scale: Polling thousands of files per second will overwhelm disk I/O and cause delays.
Manual intervention: Failures require manual investigation. Stuck files in the drop folder may not be cleaned up automatically.
No standardized error handling: No agreed format for error messages. Receiver must infer failure (no receipt file, file in error folder) and contact sender to understand what went wrong.
Fragile: Network interruptions, file-server reboots, or permission changes can silently break the integration.
Limited monitoring: No HTTP status codes or response messages. Troubleshooting relies on file timestamps and log files.
Bandwidth overhead: Batch envelopes (FHS, BHS, BTS, FTS) add overhead compared to raw HL7 messages.

Examples

Example 1: Single-message file (no batch envelope)

A simple HL7 ADT message written to a file:

File: MSG20260701120000.hl7

MSH|^~&|REGMGR|HOSPITAL|HL7RECV|HOSPITAL|20260701120000||ADT^A01^ADT_A01|MSG000123|P|2.5.1
EVN|A01|20260701120000|||SYSTEM
PID|1||MRN123456^^^HOSPITAL~12345^^^NPI||Doe^Jane^M||19800615|F|||123 Main St^^Chicago^IL^60601^USA||^^^^^(312)555-0123|^^^^^(312)555-0124||S|C|||||||||||||||||N
NK1|1|Doe^John|SPO|123 Main St^^Chicago^IL^60601||^^^^^(312)555-0199
PV1|1|I|CARDIO^ICU^BED01^A|H|||001234^Smith^John^Dr.||CAR|||N||||2|||001234^Smith^John^Dr.|||||||||||||||||||20260701100000

Processing:

Receiver scans the drop folder.
Finds MSG20260701120000.hl7.
Reads the file, parses MSH, PID, NK1, PV1 segments.
Processes the admission in the EHR.
Moves the file to archive/MSG20260701120000.hl7 or writes a receipt file MSG20260701120000.hl7.ack.

Example 2: Batch file with multiple messages and envelope

A file containing multiple ADT messages wrapped in batch envelope segments:

File: BATCH_20260701.hl7

FHS|^~&|REGMGR|HOSPITAL|HL7RECV|HOSPITAL|20260701120000|BATCH_20260701|P|2.5.1
BHS|^~&|REGMGR|HOSPITAL|HL7RECV|HOSPITAL|20260701120000|BATCH_20260701|P|2.5.1|1|2|N
MSH|^~&|REGMGR|HOSPITAL|HL7RECV|HOSPITAL|20260701120000||ADT^A01^ADT_A01|MSG000123|P|2.5.1
EVN|A01|20260701120000|||SYSTEM
PID|1||MRN123456^^^HOSPITAL||Doe^Jane^M||19800615|F|||123 Main St^^Chicago^IL^60601^USA
PV1|1|I|CARDIO^ICU^BED01|H|||001234^Smith^John^Dr.||CAR
MSH|^~&|REGMGR|HOSPITAL|HL7RECV|HOSPITAL|20260701120005||ADT^A02^ADT_A02|MSG000124|P|2.5.1
EVN|A02|20260701120005|||SYSTEM
PID|1||MRN654321^^^HOSPITAL||Smith^John^M||19750812|M|||456 Oak Ave^^Chicago^IL^60602^USA
PV1|1|I|WARD^GENERAL^BED05|H|||005678^Johnson^Mary^Dr.||MED
BTS|2
FTS|1|2

Breakdown:

FHS: File header with batch ID BATCH_20260701, sent from REGMGR at HOSPITAL at 20260701120000.
BHS: Batch header indicating 2 messages.
MSH + segments (Message 1): ADT^A01 for patient MRN123456 (Doe, Jane).
MSH + segments (Message 2): ADT^A02 for patient MRN654321 (Smith, John).
BTS: Batch trailer confirming 2 messages.
FTS: File trailer confirming 1 batch and 2 messages total.

Receiver processing:

Opens BATCH_20260701.hl7.
Parses FHS segment (file metadata).
Parses BHS segment (batch metadata, expecting 2 messages).
Extracts MSH (Message 1), parses PID, PV1, processes admission for Doe, Jane.
Extracts MSH (Message 2), parses PID, PV1, processes transfer for Smith, John.
Verifies BTS count matches (2 messages processed).
Verifies FTS count matches (1 batch, 2 messages total).
Moves file to archive or writes receipt.

Example 3: NextGen Connect (Mirth) file-reader configuration

A Mirth file listener channel polling a drop folder:

<!-- Mirth File Reader Channel -->
<channel name="HL7-FileDrop-Receiver" enabled="true">
  <sourceConnector>
    <name>File Reader</name>
    <properties>
      <fileReaderProperties>
        <host>0.0.0.0</host>
        <port>0</port>
        <directoryUrl>\FILESERVERHL7_Drop</directoryUrl>
        <fileFilter>*.hl7</fileFilter>
        <pollInterval>60000</pollInterval>  <!-- 60 seconds in milliseconds -->
        <pollingType>INTERVAL</pollingType>
        <processWithoutConnector>false</processWithoutConnector>
        <includeSubdirectories>false</includeSubdirectories>
        <ignoreDot>true</ignoreDot>
        <moveToDirectory>\FILESERVERHL7_Droparchive</moveToDirectory>
        <moveToErrorDirectory>\FILESERVERHL7_Droperror</moveToErrorDirectory>
        <checkFileModificationDate>true</checkFileModificationDate>
        <fileAge>5000</fileAge>  <!-- 5 seconds: wait for file to stop being written -->
        <sortBy>MODIFICATION_DATE</sortBy>
        <readUntilNoFiles>false</readUntilNoFiles>
      </fileReaderProperties>
    </properties>
  </sourceConnector>

  <destinationConnector>
    <name>Database Writer (EHR)</name>
    <properties>
      <databaseWriterProperties>
        <!-- Insert processed message into EHR database -->
        <host>ehr.hospital.org</host>
        <port>5432</port>
        <database>ehrdb</database>
        <username>hl7_user</username>
        <password>encrypted_password</password>
      </databaseWriterProperties>
    </properties>
  </destinationConnector>
</channel>

<!-- Mirth File Writer Channel (Write receipts) -->
<channel name="HL7-FileDropReceipt" enabled="true">
  <sourceConnector>
    <!-- Triggered when message processing completes -->
  </sourceConnector>

  <destinationConnector>
    <name>File Writer (Receipt)</name>
    <properties>
      <fileWriterProperties>
        <directoryUrl>\FILESERVERHL7_Dropreceipt</directoryUrl>
        <filename>${originalFilename}.ack</filename>
        <template>
SUCCESS
Message ID: ${messageId}
Timestamp: ${date('yyyy-MM-dd HH:mm:ss')}
Patient: ${patient.familyName}, ${patient.givenName}
        </template>
        <outputFileMode>APPEND</outputFileMode>
      </fileWriterProperties>
    </properties>
  </destinationConnector>
</channel>

Example 4: Failure-mode error file and log

Scenario: Receiver encounters a malformed message in a batch file.

File: BATCH_20260701.hl7

FHS|^~&|REGMGR|HOSPITAL|HL7RECV|HOSPITAL|20260701120000|BATCH_20260701|P|2.5.1
BHS|^~&|REGMGR|HOSPITAL|HL7RECV|HOSPITAL|20260701120000|BATCH_20260701|P|2.5.1|1|2|N
MSH|^~&|REGMGR|HOSPITAL|HL7RECV|HOSPITAL|20260701120000||ADT^A01^ADT_A01|MSG000123|P|2.5.1
EVN|A01|20260701120000|||SYSTEM
PID|1||INVALID_MRN|||...
PV1|1|...
BTS|1
FTS|1|1

Receiver processing fails:

File is moved to error/BATCH_20260701.hl7 instead of archive/.

Error log:

[2026-07-01 12:01:30.456] ERROR [FileReader] Failed to process BATCH_20260701.hl7:
  ca.uhn.hl7v2.HL7Exception: Parsing failed for message MSG000123
    at ca.uhn.hl7v2.parser.GenericParser.parse(GenericParser.java:123)
  Segment PID (line 3):
    ca.uhn.hl7v2.model.DataTypeException: Cannot instantiate data type [CX]: INVALID_MRN is not a valid CX
  Message content:
    FHS|^~&|REGMGR|HOSPITAL|HL7RECV|HOSPITAL|20260701120000|BATCH_20260701|P|2.5.1
    BHS|^~&|REGMGR|HOSPITAL|HL7RECV|HOSPITAL|20260701120000|BATCH_20260701|P|2.5.1|1|2|N
    MSH|^~&|REGMGR|HOSPITAL|HL7RECV|HOSPITAL|20260701120000||ADT^A01|MSG000123|P|2.5.1
    PID|1||INVALID_MRN|||...  <-- Invalid MRN format
  Action: File moved to /HL7_Drop/error/BATCH_20260701.hl7 for manual investigation.
[2026-07-01 12:01:31.123] WARN [FileReader] Operator notification: check error folder for unprocessable files.

Operator investigation:

Operator checks /HL7_Drop/error/ and finds BATCH_20260701.hl7. Reviews the error log, identifies the invalid MRN in PID-3, and contacts the sender. Sender corrects the file, renames it, and re-uploads. Receiver picks it up on the next poll cycle.

Vorro support for shared folder / file-drop

Vorro's File Reader module connects to SMB/CIFS shares, NFS mounts, SFTP, and FTP directories. Vorro polls the configured folder at a specified interval (default 60 seconds) and scans for files matching a pattern (e.g., *.hl7). When a new file is detected, Vorro checks the file's modification time and waits for it to stabilize (configurable delay, default 5 seconds) to ensure the sender has finished writing. Vorro then opens the file, parses HL7 v2 content, and extracts individual messages from batch envelopes (if present). Each message is passed through Vorro's transformation pipeline.

When processing completes, Vorro optionally moves the file to an archive folder, writes a receipt file (.ack) indicating success or failure, or deletes the file entirely. Vorro logs all operations (open, parse, move, delete) with timestamps for audit compliance.

Vorro can also act as a File Writer: it constructs HL7 messages, optionally wraps them in batch envelopes, and writes them to a file-share drop folder using atomic write-then-rename to ensure the receiver does not read incomplete files.

Sources

← Back to HL7 v2 Guide