RIDING BYTES
← All insights

October 31, 2026 · 6 min read

Instrument imports: from a result file to submitted results

How SENAITE reads an instrument's result file, matches each value to a sample and an analysis, and what to check when a value does not arrive. Manual upload, folder-based auto import, and the settings in between.

Instrument imports: from a result file to submitted results

Most labs have at least one instrument whose results are still typed in by hand from a printout or a screen. Every typed value is a chance for a transposition error, and every one of them has to be caught at verification. If the instrument can write its results to a file (CSV, TXT, XLSX, XML), SENAITE can read that file instead.

This post explains what happens during an import, how to set one up, and where imports fail in practice.

Two parts: parser and importer

Every import interface consists of two pieces.

The parser understands one file format. It reads the file and produces, per sample, a set of values keyed by analysis keyword. SENAITE ships parsers for several dozen instrument models (Abaxis, Beckman Coulter, FOSS, Horiba, Lachat, Mettler Toledo, Roche, Seal Analytical, Shimadzu, Sysmex, Thermo Scientific, Varian and others), plus the generic 2-Dimensional-CSV interface.

The importer is the same for all of them. It takes the parsed values, finds the matching sample and analysis, writes the result and submits it.

Setting up an instrument

On the instrument (Setup, Instruments) pick one or more interfaces under Import Data Interface. Only analyses that run on this instrument should take results from it, so check that the analysis services list the instrument as well.

If no vendor parser fits, the generic interface often does. It reads a simple table: the first column is the sample ID, the other columns are analysis keywords.

ID,PH,COND,NO3,end
W-0101,7.42,512,8.1,
W-0102,7.38,498,12.6,
end

Most instrument software can export a table of this shape, or be made to with a small template. The end markers are tolerated for compatibility and can be left out.

Part of the instrument edit form: the Import Data Interface list starting with None, 2-Dimensional-CSV, Abaxis VetScan VS2, Abbott m2000 Real Time, and below it the Result files folders table with Interface Code and Folder to import the instrument results from.
On the instrument: the import interfaces it supports, and per interface the folder for automatic import.

A manual import, step by step

Choose Import from the menu at the top right, pick the instrument and the interface, and upload the file. Two advanced options decide what the import may touch:

  • Samples state: Received (default) or Received and to be verified. Samples in other states are ignored.
  • Results override: Don't override results (default), Override non-empty results, or Override non-empty results (also with empty).

With the defaults, an import only fills empty results on received samples. That is the right setting for daily work. Overriding is for a re-run after a calibration problem, and should be a deliberate choice.

For the file above, the importer then:

  1. Looks up W-0101 as a sample ID. If nothing is found, it tries the client sample ID.
  2. Finds the analysis with keyword PH on that sample, in state Unassigned, Assigned or To be verified.
  3. Writes 7.42 as the result, and submits the analysis.
  4. Recalculates any calculated analyses on the sample that depend on the imported values.
  5. If the analysis sits on a worksheet, attaches the import file to that worksheet.

At the end it shows a log with every value it wrote and every row it skipped, with the reason.

Imported results still need verification

By default, imported analyses are submitted straight away (Submit Analyses upon import under Site Setup, SENAITE Registry, Import). They land in To be verified and go through the same verification as typed results. The import removes typing, not review. See multi-level verification for how verification is configured.

If the lab wants analysts to look at imported values before they are submitted, switch that setting off. The values are then written and the analyst submits them on the worksheet.

The import file is attached to the worksheet, so the raw data stays next to the results. With Attach import file to Analyses (off by default) it is linked to each imported analysis as well.

Calculated analyses and result options

An analysis with a calculation does not take a result from the file. The importer logs “Skipping result” for it. What it does take are the calculation’s interim fields: put the interim keywords as columns in the file, and SENAITE calculates the result. For a dry-mass correction, for example, the file carries the wet-mass value and the factor; the corrected result is computed in SENAITE, with the formula the lab validated. See SENAITE calculations.

For analyses with result options, the file can carry the numeric value of the option, and the importer selects the matching entry.

Automatic import from a folder

For instruments that write their files to a network share, SENAITE can pick them up on its own. On the instrument, Result files folders holds one folder per import interface. The folder must be reachable by the SENAITE server process, which is where most setups need a word with IT about mounts and permissions.

A cron job then calls the auto_import_results view of the site at regular intervals; the button Manually trigger auto import runs the same thing on demand. For each new file, SENAITE runs the import and writes two files into the folder:

  • imported.csv lists the file names already processed, so nothing is imported twice.
  • logs.log holds the same log the manual import shows.

Two consequences follow from this design. A file that was fixed and saved again under the same name is not imported again; give it a new name. And the override options of the cron call default to “do not override”, which is the safe choice for unattended runs.

When a value does not arrive

The log says why. The common causes, in the order we see them:

The keyword does not match. The column header must be the analysis keyword, not its title. NO3 and Nitrate are different things to the importer.

The sample is not received. With the default Samples state, a sample that is still Sample due is skipped.

A result is already there. Without override, an existing value is kept and logged.

The analysis is calculated. The file must carry the interim values, not the final result.

The ID is ambiguous. Client sample IDs are not unique in every lab. If two samples carry the same client sample ID, the importer refuses the row with “More than one Sample found”.

Two analyses with the same keyword. If a sample carries two open analyses with the same keyword, the importer cannot decide and skips the value.

Read the log after every import for the first weeks. It is the fastest way to find mismatched keywords and sample states.

When no parser fits

A parser for an unusual format is a small Python class: it extends InstrumentCSVResultsFileParser (or the TXT variant) and implements _parseline, which turns one line of the file into values per sample and keyword. Encoding, line handling and error collection come from the base class. It is registered as an adapter in a project add-on and then appears in the interface list like the built-in ones.

How long that takes depends on the file. A clean table is quick. A vendor export with multiple header blocks, per-replicate rows and units embedded in the values takes longer, and the effort goes into understanding the file, not into the code. Ask for real export files from the instrument early, including the awkward cases: a re-measured sample, a value below the detection limit, an aborted run.

For instruments that talk over a serial or network connection instead of writing files, see senaite.astm. The other direction, sending the run list to the instrument, is covered in instrument exports.

Two people reviewing notes on paper next to a laptop

Bring this to your lab

Whether you are evaluating SENAITE, scaling it across sites, or wiring up instruments and monitoring, the team that wrote the platform is the team you talk to.