Y26-246 - Receive labware/samples from Sapio

User story

When work is requested in Sapio for a pipeline that is still processed using Sequencescape / Limber, Sapio will send the relevant labware and samples to Sequencescape via the Integration Hub. This story is to create or adapt a Sequencescape endpoint for the purposes of this integration.

Who are the primary contacts for this story

Katy, Sabrine

Who is the nominated tester for UAT

We can test it internally (PSD), and in combination with the Integration Hub.

Acceptance criteria

Consider if these features can be featured flagged to decouple testing and deployment.
To be considered successful the solution must allow:

• Sequencescape exposes an endpoint for Integration Hub to call
• It accepts an array of labware (1 or more) - see mandatory and optional attributes below
• Labware are saved as generic 'stock' purposes. (different depending on whether tube/plate/library/multiplexed library - can be worked out from above data)
• For each labware, Sequencescape behaves differently if it recognises it or not:
  • If the barcode is not known, it creates new labware, samples etc., saving the given uuids and setting the samples to 'externally managed' (new field).
  • If the barcode is known, it checks further matching criteria (see Additional Context)
    • If it's a match, it does nothing for that labware (does not update anything including uuid, returns success code).
    • If it's not a complete match, whole operation fails and SS returns appropriate error code and message.
• Sequencescape API (Yard) documentation is updated
• Processing is synchronous, and appropriate http status codes and messages are returned
• (TBC) Consider audit object like 'reception' or 'sample_import', or use of existing 'sample_manifest'. Could also consider asynchronous processing.
• (TBC) Do we need to link imported samples to any studies?

N.B. The lists below may change based on the outcome of https://github.com/sanger/sequencescape/issues/6021

Labware mandatory fields:

• whether it's a plate or a tube
• uuid (set by Sapio)
• barcode
• number of wells e.g. 96, 384 (if plate)
• an array of samples (1 or more) (per-well, if plate)

Samples mandatory fields:

• uuid (set by Sapio)
• supplier sample name
• other ids / names...TBC
• tag(s) (if library)

Samples optional fields:

• donor id

Additional context

Criteria for a 'match':

• labware barcode matches, same wells (if plate) are populated, same number of samples in each well, samples match on 'supplier name'

The suggested way of implementing this does not follow the JSON:API spec, because it is a) bulk creation, and b) multi-type creation. We think this is worth it though because:
a) it will be more performant - one API call rather than many
b) it will be atomic - benefits such as easier error handling and fault recovery
c) the code will be simpler on the integration hub side

Saving the Sapio uuid against the labware means that any events SS creates in the event warehouse will link to the stock resource created by Sapio in mlwarehouse (if Sapio creates stock resource records).

Saving the Sapio uuid against the labware means that any records SS creates in mlwarehouse or event warehouse with references to samples will be linked to the sample records created by Sapio in mlwarehouse.

Deployment notes

TBC

Start with the Sequencescape API (Yard) and review issue #6021 before settling the request fields. Map the synchronous bulk labware and sample operation against the acceptance criteria, including known-barcode matching, atomic failure behavior, UUID persistence, and documentation. Done means the endpoint, status codes, matching rules, feature-flag decision, and Yard documentation are agreed and tested with the Integration Hub.