Skip to content

Instrument parser profiles

A parser converts an incoming instrument artifact into structured FlaskTrack data.

Instrument parser profiles page
Parser profiles convert instrument output into consistent fields for downstream review.

The connector answers where the data comes from. The parser profile answers how FlaskTrack interprets it.

What a parser produces

Depending on the result format, parsing can create:

  • an instrument run;
  • run metadata;
  • run positions such as wells or other source positions;
  • scientific observations;
  • numeric, text, boolean, timestamp, or structured JSON values;
  • measurement units;
  • channels or wavelengths;
  • source sample identifiers;
  • plate barcodes or well names when present in the input.

Parser profile fields

A parser profile contains:

  • optional instrument assignment;
  • profile name;
  • parser key;
  • parser version;
  • enabled state;
  • configuration JSON;
  • mapping-rules JSON.

Parser key and version

Parser keys and versions are exact identifiers.

Example:

Parser key:     generic.csv.long.v1
Parser version: 1

Use the parser key documented for the instrument export format in your FlaskTrack deployment. A file that looks like CSV is not necessarily compatible with every CSV parser; column names, layout, delimiters, and metadata conventions still matter.

Instrument-specific profiles

A profile can be assigned to a specific instrument or be available more generally, depending on your configuration.

Use an instrument-specific profile when:

  • the export layout is unique to that device;
  • column mapping differs from similar instruments;
  • units or channels need device-specific interpretation;
  • the instrument requires custom mapping rules.

Configuration JSON

Configuration JSON changes parser behavior without changing the source artifact.

The supported keys depend on the selected parser implementation. Do not add arbitrary configuration values unless they are documented for that parser.

Example shape:

{
  "delimiter": ",",
  "has_headers": true
}

has_headers is the supported key for generic.csv.long.v1. Other parser implementations may use a different configuration contract.

Mapping rules JSON

Mapping rules can provide parser-specific instructions for turning source fields into FlaskTrack fields.

The exact structure depends on the parser. Keep mapping rules version-controlled through your normal FlaskTrack change process when they affect scientific interpretation.

Selecting a parser from a connector

A connector can provide its parser key and parser version. When an artifact is received, FlaskTrack uses that configuration to choose how the worker should parse the artifact.

Where a compatible parser profile is available, ingestion details can show the selected parser profile and parser identity.

Changing a parser after an ingestion

Administrators can inspect an ingestion and, where the ingestion state permits it, select a compatible parser and retry processing.

Reprocessing a run that has already been mapped or entered controlled review may be restricted. FlaskTrack prevents parser output from silently replacing a review-controlled instrument run.

Before using a parser on production instrument data:

  1. collect representative files from the instrument;
  2. include normal, boundary, and known-failure examples;
  3. verify position counts;
  4. verify observation names and units;
  5. verify numeric values against the source artifact;
  6. verify timestamps and instrument metadata;
  7. verify source sample identifiers and plate/well identities;
  8. confirm invalid files fail safely rather than producing plausible but incorrect results;
  9. document the parser key and version used for the validated workflow.

Parser changes

Treat changes to parser configuration or parser version as changes to the data pipeline. Review the effect on downstream runs, mappings, reports, and regulated workflows before changing a production profile.

Parse projected CSV from API and stream sources

The agent can project JSON records from REST/vendor HTTP, JSON Serial, and JSON MQTT into CSV. Configure the CSV header-to-JSON-pointer rows on the connector, then configure the parser profile for those resulting headers.

For headers run_id,position,measurement,value,unit, use parser key generic.csv.long.v1, version 1, with:

{
  "delimiter": ",",
  "has_headers": true,
  "trim_values": true,
  "default_position_type": "well",
  "default_measurement_type": "instrument_result",
  "columns": {
    "run_id": "run_id",
    "run_name": null,
    "position": "position",
    "position_type": null,
    "sample_id": null,
    "plate_barcode": null,
    "well": "position",
    "observation": "measurement",
    "measurement_type": null,
    "value": "value",
    "value_type": null,
    "unit": "unit",
    "channel": null,
    "measured_at": null,
    "quality_status": null
  }
}

Choose a position type/measurement type suitable for the experiment rather than copying the example blindly. Add timestamps and sample identifiers to both projection and parser configuration when your source provides them. Configure unused optional columns as null.

For this generic parser, Mapping rules JSON can be {}. It does not automatically resolve a controlled sample record from arbitrary mapping-rule keys. Use position mapping to establish that relationship.

Raw JSON, native Opentrons JSON, and proprietary SDK output need a compatible deployed parser or a defined transformation. The virtual robot CSV demo does not validate parsing of live Robot Server JSON.

A parser profile referenced by existing ingestions cannot be deleted through the new profile delete handler. Disable it instead to retain the processing context.