File watcher pipelines

File watcher is the recommended starting point for instruments that already export completed result files.

It works well when the instrument or vendor software can write a stable CSV, TSV, JSON, XLSX, FCS, mzML, image, or other parser-supported artifact to a directory accessible by the Instrument Agent.

Cloud deployment model

The directory does not need to be visible to FlaskTrack itself.

Instrument software
       ↓ writes results
Local or network directory
       ↓ monitored locally
Instrument Agent
       ↓ outbound HTTPS
FlaskTrack

Choose the agent host

Good agent hosts include:

• the instrument workstation, when permitted;
• a laboratory integration PC;
• a small always-on Linux host;
• a laboratory server or VM;
• another managed machine that can read the result share.

The host should remain available whenever results need to be transferred.

Create the connector

Example:

Name:             Plate Reader Results
Instrument:       Plate Reader 01
Instrument Agent: Main Lab Agent
Connector type:   File watcher
Direction:        Inbound
Watch path:       C:\Reader\Exports
File pattern:     *.csv
Polling interval: 30
Parser key:       generic.csv.long.v1
Parser version:   1
Enabled:          Yes

File stability

The agent does not immediately upload a file simply because it exists.

It records the file size and modification time and waits until the file remains unchanged for the configured settle period.

This avoids reading a partial export while the instrument still has the file open.

Example:

{
  "settle_seconds": 2
}

For slow exports, increase the settle period.

Durable staging

When a source file is eligible, the agent:

1. copies it into its local spool;
2. calculates SHA-256 while copying;
3. creates a durable spool record;
4. attempts the FlaskTrack upload;
5. retries temporary failures without requiring the instrument to recreate the file.

This means an internet outage after staging does not require the original result to remain continuously available for the upload retry.

File naming

FlaskTrack receives the source filename as a filename, not as a trusted server path. Avoid relying on local directory paths as scientific identity.

Use explicit fields inside the result format for identifiers such as:

• sample ID;
• plate barcode;
• well name;
• run ID;
• batch ID;
• operator;
• method name.

Network shares

For a share, configure mounting and authentication at the operating-system layer.

Then point the FlaskTrack connector at the resulting accessible path.

Windows:

\\LAB-NAS\InstrumentResults\Reader01

Linux:

/mnt/instruments/reader01

Do not assume a user-session drive letter is available to a Windows daemon running as SYSTEM.

Archiving source files

If the laboratory wants the agent to move successfully uploaded files out of the inbox:

{
  "source_file_action": "archive",
  "archive_dir": ".flasktrack-archive"
}

The archive directory can be relative to the watch root or configured according to your deployment.

Use leave if another validated process owns source-file retention.

Test procedure

For a new file watcher:

1. create a small known-good result file;
2. place it in the watch directory;
3. run flasktrack-agent once;
4. wait for the settle period if necessary and run it again;
5. confirm the artifact appears in Instrument Ingestions;
6. compare source checksum/filename expectations;
7. verify parsed positions and observations;
8. verify required mappings;
9. complete review according to your procedure.

Repeat the test with one deliberately invalid file to confirm the parser fails safely.