senaite.astm 2.0: HL7 neben ASTM und Werkzeuge für die Inbetriebnahme

Viele Analysegeräte in Klinik- und Veterinärlaboren schreiben keine Ergebnisdateien. Sie halten eine Netzwerk- oder serielle Verbindung zu einem Host-System und schicken jedes Ergebnis als Nachricht, in ASTM (LIS2-A2) oder HL7 v2. Für diese Geräte greifen Datei-Importe nicht. senaite.astm ist die Middleware für sie: ein kleiner Python-3-Dienst, der auf das Gerät wartet, jede Nachricht parst und an SENAITE weitergibt.

Version 2.0 liegt im Branch 2.x des Repositorys. Sie ist noch nicht auf PyPI veröffentlicht; installiert wird sie aus GitHub.

Wie die Teile zusammenspielen

senaite.astm nimmt die Verbindung an, wickelt den Protokoll-Handshake ab und zerlegt die Nachricht in einen JSON-Envelope mit einem Bereich pro Satzart: Kopf (H), Patient (P), Auftrag (O), Ergebnis (R), Kommentar (C) und einige weitere. Den Envelope schickt es an den Push-Endpunkt der SENAITE JSON-API.

Der SENAITE-Kern nimmt den Envelope über den Push-Consumer senaite.core.lis2a.import entgegen. Der Consumer liest den Absendernamen aus dem Kopf und übergibt den Envelope an einen Importer, der unter diesem Namen registriert ist. Der Basis-Importer findet das Gerät in SENAITE über Modell oder Titel und Seriennummer, und die Probe über die ID in der Nachricht.

Der Importer für das Gerät entscheidet, was wohin gehört: welcher Ergebnissatz zu welchem Schlüsselwort einer Analyse gehört, was mit Flags und Einheiten geschieht, ob die Rohnachricht angehängt wird. Dieser Teil entsteht pro Gerätemodell im Projekt-Add-on. senaite.astm weiß, wie die Nachrichten eines Geräts aufgebaut sind; es weiß nicht, wie Ihr Labor seine Analyseleistungen benannt hat.

Diese Aufteilung sollten Sie verstanden haben, bevor Sie eine Anbindung planen. Die Middleware ist für die unterstützten Geräte fertig. Die Zuordnung zu Ihren Analyseleistungen ist Projektarbeit, meist überschaubar, sobald echte Nachrichten vorliegen.

Geräte mit Parsing-Schema

Version 2.0 enthält Nachrichtenschemata für Abbott Afinion 2, bioMérieux mini VIDAS, Siemens DCA Vantage, Cepheid GeneXpert, Hitachi 7600, Horiba Pentra XLR, Horiba Yumizen H5xx, Roche cobas c111 und c311, Spotchem EL (SE-1520), Sysmex XN und Sysmex XP. Geräte außerhalb der Liste sprechen oft so nah am ASTM-Standard, dass ein neues Schema wenig Arbeit ist; das muss aber an der Schnittstellenspezifikation des Geräts geprüft werden.

Was 2.0 neu bringt

Ein HL7-v2-Empfänger. senaite-hl7-server nimmt HL7 v2 über MLLP entgegen, standardmäßig auf Port 2575, und quittiert jede Nachricht auf Transportebene. Er ordnet die Segmente denselben Bereichen zu, die der ASTM-Parser erzeugt: MSH zu H, PID zu P, OBR zu O, OBX zu R, NTE zu C. Die Felder tragen ihre HL7-Feldnummer als Schlüssel, OBX-3 ist also R[i]["3"]. Segmente außerhalb dieser Liste bleiben unter metadata.unmapped_segments erhalten, der Originaltext der Nachricht unter metadata.hl7. Ein Importer kann ASTM- und HL7-Geräte also gleich behandeln.

Eine Grenze sollten Sie kennen: Der Standard-Consumer des HL7-Servers, senaite.core.hl7.import, ist im SENAITE-Kern nicht registriert. HL7-Ergebnisse in SENAITE zu bringen braucht einen Consumer und Importer auf Projektseite. Ohne --url läuft der HL7-Server als reiner Mitschnitt.

Reiner Mitschnitt. senaite-astm-server --capture-only -o DIR nimmt Verbindungen an und schreibt jede Sitzung auf die Platte, ohne SENAITE zu kontaktieren. Zusammen mit --url wird die Option abgelehnt, ein falsch konfigurierter Dienst scheitert also beim Start, statt Nachrichten still zu verwerfen.

Mitschnitte im Normalbetrieb. Mit -o DIR wird jede Sitzung auch während der Weitergabe auf die Platte geschrieben, mit Mikrosekunden-Zeitstempeln im Dateinamen. Ist SENAITE nicht erreichbar und sind die Wiederholungsversuche erschöpft, liegt der Mitschnitt noch zum erneuten Senden bereit.

Ein Werkzeug zum erneuten Senden und Umwandeln. senaite-astm-send schickt Mitschnitte erneut an SENAITE. Nützliche Optionen: --dry-run zeigt, was gesendet würde, --validate-only prüft, ob ein Mitschnitt sich parsen lässt, --substitute-sample-id ALT=NEU lenkt einen Mitschnitt auf eine Testprobe um (mit --rebuild-checksums, weil die Änderung die Prüfsumme des Frames bricht), und --scrub-phi ersetzt jedes Patientenfeld, das nicht auf einer kurzen Positivliste steht, durch <REDACTED>, bevor ein Mitschnitt auf ein Testsystem geht.

Ein Werkzeug zur Inspektion. senaite-astm-inspect liest Mitschnitte, ohne etwas zu senden: instrument zeigt, welches Schema gegriffen hat, summary zählt die Sätze pro Datei, diff vergleicht zwei geparste Mitschnitte.

Ein Statistik-Endpunkt. --admin-port öffnet einen schreibgeschützten HTTP-Endpunkt, dessen GET /stats JSON mit uptime_seconds, active_sessions, frames_dispatched und last_dispatch_at liefert. Er lauscht standardmäßig nur auf 127.0.0.1, weil er keine Authentifizierung hat.

Betriebsfestigkeit. Die Übergabe an SENAITE hat ein Timeout (10 Sekunden für den Verbindungsaufbau, 60 für das Lesen) und Wiederholungen (-r, Standard 3, -d, Standard 5 Sekunden Abstand); Antworten 401 und 403 werden nicht wiederholt, weil sie neue Zugangsdaten brauchen, keine Geduld. Bei SIGTERM wartet der Server bis zu --shutdown-grace-seconds (Standard 30) auf Nachrichten, die gerade verarbeitet werden.

Ein Gerät in Betrieb nehmen

In dieser Reihenfolge gehen wir vor, wenn ein neues Analysegerät angebunden wird.

1. Zuerst mitschneiden. Den Server im reinen Mitschnitt-Modus im Gerätenetz starten und das Gerät einen normalen Arbeitstag senden lassen, einschließlich eines QC-Laufs und einer Wiederholungsmessung.
2. Inspizieren. senaite-astm-inspect summary und instrument zeigen, ob das Schema passt und was die Nachrichten enthalten: wo die Proben-ID steht, welche Testcodes die Ergebnisse tragen, welche Flags vorkommen.
3. Den Importer schreiben. Im Projekt-Add-on die Testcodes des Geräts den Schlüsselwörtern der Analysen zuordnen, mit den echten Mitschnitten als Testdaten.
4. Gegen ein Testsystem wiederholen. senaite-astm-send mit --substitute-sample-id und --scrub-phi schickt die Mitschnitte in ein Test-SENAITE mit Testproben, bis jedes Ergebnis dort landet, wo es hingehört.
5. Produktiv gehen mit -o und --url zugleich, damit jede Nachricht weitergegeben und zusätzlich auf der Platte aufbewahrt wird.

Betrieb

Ein minimaler Produktivstart des ASTM-Empfängers:

senaite-astm-server \
    -p 4010 \
    -o /var/lib/senaite-astm/captures \
    -u https://user:password@lims.example.com/senaite \
    --admin-port 4011 \
    --logfile /var/log/senaite-astm/server.log

Die Deployment-Hinweise im Repository enthalten eine systemd-Unit und einen Abschnitt für supervisord. Lassen Sie den Empfänger unter einem eigenen Benutzer laufen, begrenzen Sie den Port per Firewall auf das Gerätenetz und halten Sie die Zugangsdaten aus der Unit-Datei heraus. Geben Sie dem Empfänger ein eigenes Konto in SENAITE, damit seine Importe im Audit-Log erkennbar sind.

Für das Monitoring fragen Sie /stats ab: uptime_seconds sollte zwischen zwei Abfragen wachsen, und last_dispatch_at sollte während der Arbeitszeit nicht älter sein als der übliche Abstand zwischen zwei Nachrichten. Ein Gerät, das nicht mehr sendet, fällt dem Labor irgendwann auf; ein Alarm fällt es früher auf.

Wann Sie uns ansprechen sollten

Planen Sie, Analysegeräte mit ASTM oder HL7 anzubinden, schicken Sie uns zuerst das Gerätemodell und seine Host-Schnittstellenspezifikation. Daran sehen wir, ob ein Schema existiert, was der Importer braucht und wie viel der Arbeit Konfiguration ist. Nehmen Sie Kontakt auf.