Context
A research team sends instrument measurements into a laboratory system, runs an analysis, and prepares a result for scientific review. Each application has a legitimate view of the work. The instrument knows the run and well position. The laboratory system knows the sample and its processing history. The analysis environment knows the input files, parameters, and software version. The reviewer needs to understand how those records belong together.
This is a representative design case, not a report of a client implementation. It examines the decisions a team could make when a technically successful integration leaves its users unsure whether the result in front of them is complete, current, and fit for the next step.
The problem
Consider an instrument export containing a sample label, a numeric value, and a run timestamp. The receiving application accepts the file and displays “Import complete.” Later, a reviewer discovers that the same sample label appears in another study, the unit was inferred from a default, and a corrected export has created a second result instead of replacing the first result's current status.
Nothing in the transport layer necessarily failed. The file arrived and its rows were parsed. The failure is in the agreement between the systems: what identifies the material, what the value means, and what the receiver is allowed to do with it. A green success message compresses those separate questions into one misleading answer.
Why the gap persists
Integration work often begins with field mapping. A source column is matched to a destination property, and the team verifies that ordinary examples appear in the receiving screen. This is useful, but it leaves decisions about ambiguity to whichever person encounters the exception first.
Local identifiers make sense inside their original scope. A timestamp may describe acquisition, export, or receipt. An empty value may mean no measurement was collected, processing failed, or the result is awaiting review. Unless these distinctions travel with the record, the receiver must reconstruct them from context it may not have.
The constraints
The team cannot assume that every instrument can adopt a new identifier scheme or that every partner can update its software at the same time. Some transfers arrive as files. Others arrive through APIs. A connection may fail after the receiver has stored a record but before the sender receives confirmation.
The design therefore needs to tolerate older formats, retries, and partial batches. It also needs a practical boundary for responsibility: an integration operator can resolve a delivery problem, while a scientific reviewer determines whether a result can be used. Granting both roles the same “approve” action would obscure that distinction.
Define the receiving contract
Start with one end-to-end result and specify what the receiving team needs to interpret it. In this scenario, the contract would include the source system, source record identifier and version, sample identifier and its scope, run identifier, measurement type, value and unit, relevant timestamps, and review state. The agreed contract should state which fields are required for each downstream use.
Keep the original payload alongside the normalized record, subject to the project's retention and access rules. Record the mapping version and transformations applied. A unit conversion should retain the original value and unit as well as the converted value, so a reviewer can inspect the operation instead of trusting an unexplained number.
W3C's PROV family provides a vocabulary for describing entities, activities, and responsible agents. It offers a useful conceptual basis for representing which input and transformation produced an output. The contract and interface proposed here are design choices for this scenario, not requirements imposed by PROV.
Separate arrival from readiness
Replace the single success state with a small set of meaningful states: received, validated, needs resolution, and released for the specified downstream use. Receipt confirms arrival. Validation checks the agreed structure and mappings. Release records an authorized decision about use. These states should have different owners and clear transition rules.
An unknown sample identifier should enter a resolution queue rather than attach silently to the closest match. The queue should show the original identifier, candidate records, the reason for ambiguity, and who can resolve it. A missing unit should remain visible as a blocking issue wherever interpretation depends on that unit.
HL7 FHIR R5 Observation illustrates why a result has more structure than a scalar value: its model includes status, specimen references, effective time, and data-absence information. It is a useful reference when relevant to the receiving environment; adopting FHIR alone would not settle local mapping or review decisions.
Make repetition and correction explicit
A retry should not become a new scientific observation. For this case, the receiver could use the source system, source record identifier, and source version as a deduplication key. Repeated delivery of the same version returns the existing receipt. A different payload carrying that same key raises a conflict for investigation instead of silently overwriting the stored content.
A correction is a different event. It creates a new version linked to its predecessor, with a reason and attribution. The earlier result remains discoverable, while the interface identifies which version is current. If the earlier version has already been used in an analysis or report, the system exposes those downstream links for impact review; it should not automatically assume every derived result must be recomputed.
For a partial batch, the operator needs record-level outcomes and a reconciled count of received, accepted, and unresolved items. Retrying only unresolved records reduces unnecessary work, but the same deduplication rules must also make a full-batch retry safe.
Evidence and trade-offs
Before release, exercise the contract with an ambiguous sample label, missing unit, duplicated delivery, changed payload under an existing version, corrected result, and interrupted batch. Check that every input has an accountable outcome and that no retry creates a duplicate observation. These are proposed acceptance checks, not measured results from a deployed system.
Ask a reviewer to trace a normalized result back to its source and explain why it is ready for use. Ask an operator to recover an interrupted transfer without changing scientific content. If either task requires a private spreadsheet or the memory of the integration developer, the handoff remains incomplete.
More explicit states introduce additional interface and operational work. Strict validation may delay a batch that previously appeared to finish immediately. Those costs should be weighed against the consequence of releasing ambiguous data. Define the required evidence by intended use, and provide a fast resolution path rather than weakening validation to make the queue disappear.
What the case shows
The practical unit of integration is a result that another team can interpret and act on responsibly. Delivery, semantic validation, correction history, and authorization for use are separate parts of that outcome.
Design each handoff around the receiving team's next decision. Preserve the source, make transformations inspectable, and give every exception an owner and a recovery path. The integration is ready when its users can explain what arrived, what changed, and why the next action is justified.