Upload über das Laborinformationssystem

Zielstellung

• Hochladen von Sequenzen und Metainformationen über DEMIS per Schnittstelle
• Bereitstellung der Metadaten im FHIR Format (https://simplifier.net/rki.demis.igs) 
• Upload von bis zu zwei Sequenzdateien im Format FASTA oder FASTQ (auch als GZip komprimiert) pro Vorgang
  
  • Maximalgröße pro Datei: 999 MB (Entpackte Größe bei gezippten Dateien ca. 6 GB)

Vorbedingungen

• Die Integration der DEMIS Schnittelle wurde auf der Testumgebung erfolgreich getestet.
  • Für die Freischaltung in der Testumgebung wenden Sie sich bitte an demis-support@rki.de
• Authentifizierung über geeignetes Verfahren in der DEMIS Schnittelle (Beispielsweise Zertifikat) 
• DEMIS-ID/Nutzer ist durch das RKI für IGS freigeschaltet worden (siehe Freischaltung für IGS (Schnittstelle))

Ablauf

Das Übermitteln von Sequenzdaten erfolgt in mehreren Schritten, um die für die Übermittlung notwendigen FHIR Ressourcen zu übertragen.

Anlegen der DocumentReference

Im ersten Schritt wird eine DocumentReference-Ressource zu den Sequenzdaten angelegt. Dies erfolgt über eine FHIR create-Operation, welche durch einen HTTP-POST-Request abgebildet wird. Die DocumentReference muss insbesondere den SHA256 Hash der Datei enthalten, die später hochgeladen wird. 

Upload der Sequenzdaten

Anschließend werden die Sequenzdaten hochgeladen. Beim IGS-Storage handelt es sich um einen S3-kompatiblen Speicher, so dass für den Upload S3-Client-Bibliotheken genutzt werden können. Der Upload-Vorgang erfolgt mittels Chunk Upload in den IGS-Storage. Als Chunk Größe werden 10 MB unterstützt.  Die Authentisierung und Autorisierung des Uploads erfolgt mittels Presigned URLs. Das Labormanagementsystem fragt dazu Presigned-URLs für die hochzuladende Datei beim IGS-Service an und nutzt diese im Anschluss für den Upload in den S3. Nach dem Upload muss die Validierung der Sequenzdaten angestoßen werden. Das Ergebnis der Validierung wird in einem Long-Polling Verfahren abgefragt. Dazu sendet das Labormanagementsystem eine Anfrage an den IGS-Service welcher 15 Sekunden lang prüft, ob ein Validierungsergebnis vorliegt und den Status zurück meldet. Das Labormanagementsystem wiederholt die Anfrage, bis ein Validierungsergebnis vorliegt. Je IGS-Meldung können auf diese Weise ein oder zwei Sequenzdaten verknüpft und bereitgestellt werden.

Upload der Metadaten

Im letzten Schritt erfolgt die Bereitstellung des Sequenzdatenuploads über eine DEMIS-Nachricht, in welcher die entsprechenden IDs der DocumentReference-Ressourcen verlinkt sind. Das Senden der Nachricht erfolgt über die dafür vorgesehene FHIR-Operation $process-notification-sequence.

Endpunkte

Der IGS-Dienst wird wie folgt bereitgestellt:

Sequenzdiagramm 

Ablauf

• [ 1 ] - DocumentReference-FHIR-Ressource-Objekt erzeugen, insbesondere muss der SHA-256 kodierte Hash der hochzuladenden Datei enthalten sein
• [ 2 ] - DocumentReference mittels HTTP POST an den IGS Service senden
• [ 4 ] - Die Response enthält im Header-Element location den URL-Suffix, unter dem die Sequenzdaten später abgerufen werden können. Die DocumentReference im Body der Response enthält außerdem das Feld id, welches nachfolgend mit documentId referenziert wird.
• [ 5 ] - Anfordern der Presignend URLs zum Hochladen der Chunks. Dabei wird die documentId, welche beim Anlegen der DocumentReference erhalten wurde im Pfad kodiert und die Größe der hochzuladenden Datei in Bytes als Query-Parameter übergeben. Die Presigned URLs haben eine Gültigkeitsdauer von 12 Stunden.
• [ 6 ] - Die Response enthält die für den Upload zu verwendende Upload-ID, je Chunk eine Presigend URL, sowie die zu verwendende Chunk-Größe in Bytes.
• [ 7 ] - Die hochzuladenden Sequenzdaten müssen in Chunks der Größe partSizeBytes zerlegt werden, der letzte Chunk kann entsprechend der Datengröße kleiner sein. Der Wert partSizeBytes gibt die Chunk-Größe in Bytes an und wird in der Response in Schritt 6 zurück geliefert.
• [ 8 ] - Der Client sendet je Upload Part einen HTTP PUT Request an die presigend URL, die dem entsprechenden Chunk zugeordnet ist
• [ 9 ] - Aus dem Response Header ist das Feld ETag zu extrahieren und mit der zugehörigen Part-Nummer für die spätere Verarbeitung zu speichern
• [ 10 ] - Der Client signalisiert das Abschließen des Uploads via POST-Request finishUpload an den IGS-Service. Im Body des Requests werden die uploadId und für jeden übertragenen Part die Nummer und das beim Upload erhaltene eTag angegeben.
• [ 12 ] - Bevor die Sequenzdaten in einer Meldung referenziert werden können, müssen diese validiert werden. Der Client stößt dazu nach dem Upload der Daten in den Storage die Validierung der Sequenzdaten im IGS-Service an.
• [ 14 ] - In einem Long-Polling-Verfahren prüft der Client ob der Validierungsstatus vorliegt. Dabei wird die Response vom IGS-Dienst um bis zu 15 Sekunden verzögert. 
• [ 15 ] - In der Response verauskunftet der IGS-Service im Attribut done, ob die Validierung abgeschlossen wurde (true, wenn abgeschlossen). Mögliche Statusangaben: VALIDATING: Validierung aktiv, VALID: abgeschlossen und Daten gültig, VALIDATION_FAILED: abgeschlossen und Validierung fehlgeschlagen, VALIDATION_NOT_INITIATED: Validierung wurde noch nicht gestartet.
• [ 16 ] - Erzeugung der IGS-Nachricht gemäß Profil und allen zugehörigen DocumentReference IDs. Der Pfad für DocumentReferenceID lautet: MolecularSequence.extension[https://demis.rki.de/fhir/StructureDefinition/SequenceDocumentReference]/valueReference/reference[@value]
• [ 17 ] - POST Request zum Absenden der IGS Nachricht
  
• [ 18 ] - Die Response enthält in der Parameters-Ressource Informationen: transactionID, submitterGeneratedNotificationID und labSequenceID