Sapio LIMS

Sapio LIMS is Sapio Sciences’ laboratory information management system — the system of record for samples, orders and results. This integration is the other way round from most of the devices in this catalogue: there is no instrument, no serial port and nothing to teach a robot. Revolution talks to the Sapio web service over HTTP, and what crosses the boundary is work to do and results to file.

That makes it a device with no hardware. It occupies a device slot in a Revolution system so that a schedule can call it, and everything it does is a web request.

Two things move across the integration. Coming in, Sapio’s priority worklist — which samples matter most right now. Going out, a result written back onto a sample’s Sapio record once Revolution has finished processing it.

At a glance

Type	Software integration — no hardware, no location, no plate movement
Transport	HTTPS to the Sapio web service
Authentication	API token and application key, sent as request headers
Revolution control	Run priority batch, report sample result
Direction	Sapio decides what is urgent; Revolution decides when and how it runs

What the integration actually does

Priority scheduling driven by the LIMS

The interesting operation is run priority batch, and what makes it useful is the intersection it takes. It does not simply start a schedule because Sapio has queued work. It:

1. Asks Sapio for the pending priority worklist.
2. Reads the barcodes of the labware currently loaded in the system’s stores.
3. Keeps only the samples that appear in both — priority and physically present.
4. Groups what is left by order or assay type.
5. Starts the configured priority schedule, with those samples attached as an order.

If nothing loaded is on the priority list, it logs that and returns without starting anything. If nothing is loaded at all, likewise. So the operation is safe to call speculatively — on a timer, or at the end of every run — rather than needing something to know in advance that priority work exists.

The samples travel to the scheduler as an order, not as a schedule name. That distinction matters: starting the schedule by name alone would run it without telling it which samples are the priority ones. The order becomes the pick list the schedule’s transfer operations draw from, so the schedule processes exactly the samples Sapio flagged.

The operation also does not wait for the priority run to finish. It is itself called from a schedule thread, and blocking there would stall the schedule that triggered it.

Results written back, with a fallback that does not lose data

Report sample result writes a completed sample’s outcome — sample ID, labware position, volume and status — onto its Sapio record.

The part worth knowing is what happens when that write fails. Rather than throwing away the result, the driver persists the update to a CSV drop file in a configured fallback directory and warns the operator. The operation only fails outright if the fallback itself cannot be written — at which point the update really would be lost, so failing the schedule is the correct outcome.

This is why the fallback directory is not optional. The driver refuses to report a result at all if no fallback directory is configured, on the grounds that writing a result with no safety net is worse than not starting.

Supported methods

• Run priority batch — query Sapio for the priority worklist, intersect it with the loaded labware, and start the priority schedule for whatever matches. Takes a schedule thread count (default 1, must be at least 1)
• Report sample result — write a result back to a Sapio record. Takes a record path (relative to the base URL), a sample ID, a position (for example A1), a volume in microlitres (default 0), and a status (for example ok or failed)

Both fail with a clear error rather than a silent no-op when they are not configured to run: run priority batch requires a worklist path and a priority schedule name, and report sample result requires a record path and the fallback directory.

There is one soft failure mode to watch. If worklist records come back without a barcode in the configured barcode field, the driver warns and carries on — it counts how many records were skipped and says so in the log. That is deliberate, because one malformed record should not stop a batch, but it means a mismatch between the configured field name and Sapio’s actual contract shows up as fewer samples than expected, not as an error. If a priority batch schedules less work than you were expecting, the log is the first place to look.

Integration

The driver is an HTTP client against the Sapio web service. Every request carries the API token and application key as headers. The Sapio side of the driver is asynchronous internally and is bridged to Revolution’s synchronous operation boundary once per operation.

Three bounds are applied to protect the scheduler from a slow or misbehaving Sapio instance: a per-request timeout of 60 seconds, an overall deadline of 120 seconds for an operation, and a hard cap of 64 MB on a single response body. Exceeding the deadline fails the operation with a message naming it, rather than hanging the schedule.

Prerequisites

• A reachable Sapio instance, and an API token and application key valid for it.
• The priority schedule must exist in Revolution by name before the operation is called. The driver starts it by name and fails if the name is not configured.
• The field names must match your Sapio configuration. Barcode, order type, sample ID, position, volume and status are all configured per field, because Sapio deployments name them differently. Getting the barcode field wrong is the failure that hides rather than shouts — see above.
• A result fallback directory that Revolution can write to. Without it, result reporting is refused outright.
• Labware must be loaded with barcodes recorded in Revolution’s storage manager, since matching the worklist against what is present is done on barcode.

Device configuration

Property	Purpose
SapioBaseUrl	Base URL of the Sapio web service
SapioApiToken	API token, sent as the X-API-TOKEN request header
SapioAppKey	Application key, sent as the X-APP-KEY request header
PriorityScheduleName	Revolution schedule started for priority samples
WorklistPath	Path of the Sapio priority-worklist endpoint, relative to the base URL
WorklistItemsProperty	JSON property in the response that holds the worklist record array
BarcodeField	Record field carrying the sample barcode, used to match against loaded labware
OrderTypeField	Record field carrying the order or assay type, used to group the batch
ResultFallbackDirectory	Folder result CSV drop files are written to when an API write fails
SampleIdField	Record field the sample ID is written to
PositionField	Record field the labware position is written to
VolumeField	Record field the volume is written to
StatusField	Record field the processing status is written to

The token and key are credentials. Treat the device configuration as somewhere secrets live, and scope the Sapio account to what the integration actually needs to read and write.

If you need more of this integration driven from a schedule, get in touch — the driver is extended on demand.