File Receiver¶

Messages can be saved to a directory which QIE is configured to monitor. Matching files contained within the directory are processed as messages through the channel.

Note

When the channel's message format is DICOM, the DICOM Format section of the source node includes the Enable storing DICOM Pixel Data in a separate folder option. Enable it on any channel that can receive large DICOM files so QIE never has to hold whole instances in memory.

Zero-byte files

Zero-byte files are skipped by the file receiver. QIE assumes they are still being written and retries them on later polls. A file that stays empty past the age controlled by the -Dqie.zeroByteFileMaxAge Java option (default 1 hour) is logged as Channel '<name>' found a zero byte file: <path>, this file has been deleted. and removed from the folder. Zero-byte files never enter the inbound queue.

Path¶

The path field contains the path to the folder and the filename pattern that QIE uses when checking for files to be processed. The filename pattern can contain wildcard characters such as asterisk (*) and question mark (?). The table below gives some examples of filename patterns.

Filename Pattern	Matches
C:\Folder	All files in the 'C:\Folder' directory
C:\Folder\	All files in the 'C:\Folder' directory
C:\Folder\*.tx	All files with an extension of '.tx'
C:\Folder\*.tx?	All files with an extension that starts with '.tx' and has 1 additional character (letter or number)
C:\Folder\.tx	All files with an extension that starts with '.tx' and has zero or more additional characters
C:\Folder\*suffix.txt	All files with a name that ends with 'suffix' and have an extension of '.txt'
C:\Folder\text.*xt	All files with a name that contains 'text' and have an extension that ends with 'xt'
C:\Folder\FixedName.txt	Only files with the fixed name and extension of 'FixedName.txt'
C:\Folder.Name\	All files in the 'C:\Folder.Name' directory

Folder names that contain a period

QIE reads the last element of the path as a file name when that element contains a period. A path of C:\Folder.Name therefore looks for a file named Folder.Name inside C:\. When the final folder name contains a period, end the path with the same separator character the rest of the path uses (C:\Folder.Name\), or add a filename pattern (C:\Folder.Name\*). A trailing / on a path written with \ is not recognized. The same applies to a UNC path whose share name contains a period, such as \\server\share.name\.

The path field also accepts node tags. Channel cache values can be substituted with {cc:VariableName}, system variables with {v:VariableName}, and system date components with {SYSTEM_DATE[yyyy]} (or any standard date pattern), which is useful for routing files into per-year, per-customer, or per-environment subfolders. QIE resolves the tags on each scan.

Mapped drive letters

Windows-mapped drive letters (e.g. Z:\...) belong to the user session that created them and are not visible to services running as a different account. For a network share, enter the UNC path (\\server\share\...) directly here, or use a Network Share (SMB) node instead of the File node.

Test Path¶

The Test Path button resolves any node tags in the path against the current channel-cache and system-variable values, then verifies that QIE can access the resolved path. If the path does not exist, the channel status displays file receiver errors as soon as the channel is started.

Test Path reports the effective test path that QIE probed alongside the path as entered, on both success and failure. When a failure comes from a path whose final element is itself a folder, the message names that element: QIE tested it as a file name.

Execution¶

Execution defines the frequency and schedule associated with scanning the folder for matching files. The three available options are continuous, scheduled or manual.

If execution is set to Continuous, the folder is scanned continuously with a timeout period between folder scans equal to the 'Scan Interval'.

If execution is set to Scheduled, the folder is scanned according to the schedule specified in the associated CRON String.

If execution is set to Manual, the folder is scanned only when a user selects the Run Now button.

Run Now¶

If execution is Scheduled or Manual, use the Run Now button for immediate execution.

Scan Interval¶

When using Continuous execution, the scan interval is used to set the 'timeout' or wait period between folder scans.

CRON String¶

When using Scheduled execution, the CRON String is used to specify the schedule to be used for folder scans. See CRON String Format for the six-field syntax and examples.

Include All Subdirectories¶

Selecting this checkbox instructs QIE to scan matching files in subfolders beneath the configured Path. This is useful when inbound files are organized into date-based, customer-based or location-based folders beneath a common root. The Test Path button includes matching files found in subfolders when this option is enabled.

When this option is enabled, QIE preserves the source-relative folder as source metadata. That metadata can be referenced in archive paths, destination paths or templates using Source Metadata node tags such as {s-meta:FILE_DIRECTORY} or the source.getFileDirectory() function.

Only Process Files Older Than…¶

Checking this box delays processing a file until it has been in the folder the specified number of seconds. This can help to prevent file locks.

After Processing¶

After processing inbound files, QIE can be configured to either Delete the file or Move file to an archive location. The archive path entered here must exist or the channel is in an error state immediately after processing a file.

When Include All Subdirectories is enabled and the archive path does not use source metadata, nested folder values are flattened into the archived filename. To preserve the original relative folder structure, include source metadata node tags such as {s-meta:FILE_DIRECTORY} in the archive path. If the archive folder is located beneath the source root, QIE skips that archive tree during recursive scans.

Large File Handling Options¶

When this option is checked, the message is not stored in memory but passed to the channel as a filename which points to the file on disk. The channel must dispose of the file once it is finished using it. For the recommended mapping pattern, see Passing Through Large Files Without Loading Them Into Memory.

Preprocess Received Bytes¶

In some cases, it may be necessary to pre-process the received bytes to correct malformed messages before submitting them to the inbound queue. Configuring a preprocessor script allows the bytes to be manipulated and/or discarded before processing the message through the channel.

Run Preprocessing Script On¶

The preprocessing script can be run against all messages received or only on messages that fail to parse.

Script¶

The received bytes are available to the script as the bytesIn byte-array. To inspect or edit the content as text, convert it to a String using the channel's configured encoding, which qie.getChannelEncoding() returns. The preprocessing script must set the bytesOut variable as a byte-array. If bytesOut is set to null, the message is discarded and not submitted to the inbound queue. The preprocessing script can also be used to post a message response. To send a response, set the responseBytes variable as a byte-array.

For example, to discard files that are empty or contain only whitespace:

var content = new String(bytesIn, qie.getChannelEncoding());
if (StringUtils.isBlank(content)) {
    bytesOut = null;     // halt processing; nothing enters the inbound queue
} else {
    bytesOut = bytesIn;  // pass through unchanged
}

Troubleshooting `Unable to move file`¶

When Move file to is configured and QIE cannot complete the move, the channel logs:

java.io.IOException: Unable to move file 'D:\Inbound\roster.csv' to 'D:\Inbound\Sent\roster.csv'.

QIE moves the file with a filesystem rename, which reports only success or failure. No operating-system reason is available, so the exception never says whether the cause was a denied permission, a held lock, or something else. There is no nested exception to look for.

Three facts narrow the search.

QIE already retried. The first failure is followed by four more attempts, spaced one, two, three and four seconds apart. Each one writes a warning to the channel log:

Attempt 2 to move file 'D:\Inbound\roster.csv' to 'D:\Inbound\Sent\roster.csv' failed. Will try again in 2 seconds.

The exception is raised only after all five attempts fail across roughly ten seconds. A lock that clears quickly is already ruled out by the time the error appears.

An existing file in the archive folder is not the cause. QIE never overwrites an archived file. When the target name is taken it appends a counter and writes roster_2.csv, roster_3.csv, and so on.

The channel stops. A failed move is treated as a critical error, so the receiver shuts the channel down and logs Critical error encountered. Shutting down channel. Restarting the channel without fixing the cause produces the same failure on the next file.

What remains is a sustained hold on the file or a rights problem:

The account running QIE lacks delete or modify rights. A rename needs more than the create right that lets QIE build the archive folder. Check the effective rights on the inbound folder, the archive folder and the file itself, as the account the QIE service logs on as rather than as your interactive account.
Another process holds the file open. Antivirus, endpoint protection, a backup agent, an indexing service, or the application that writes the file can all hold it past the ten-second retry window. Enable Only Process Files Older Than so QIE waits before picking the file up.
Security software blocks the rename itself. Ransomware protection, controlled folder access and data-loss-prevention agents commonly allow a folder to be created but block a rename. Review their logs at the time of the failure.
The move crosses a volume or a network boundary. A rename that is not within one filesystem can fail where a copy would succeed.