ORM

Order Message

Mit diesen Nachrichten können PROM-Aufträge (Patient Reported Outcome Measures) aus dem KIS an samedi übergeben werden. Das HL7-Gateway parst die eingehende ORM^O01-Nachricht und übergibt den Auftrag an die samedi-Plattform, die daraus den PROM-Workflow anlegt.

Unterstützte Nachrichtentypen:

ORM^O01 - Order Message

ORM-Nachrichten werden nur verarbeitet, wenn für den über MSH-6 adressierten Account orm_enabled = true konfiguriert ist. Andernfalls wird die Nachricht mit MSA|AR und dem ERR-Text ORM not enabled for any samedi account matching this facility abgewiesen und ein Warnhinweis an die Plattform gemeldet.

`ORM^O01`

Beispielnachricht

MSH|^~\&|EHR_SYSTEM|HOSPITAL|PRO_PLATFORM|<FACILITY>|20260723120000||ORM^O01^ORM_O01|MSG00123|P|2.5.1
PID|1||<PATIENT_XREF>^^^<AUTHORITY>^PI||Doe^Jane||19700101|F
PV1|1|O|||||||||||||||||<ENCOUNTER_XREF>
ORC|NW|<PROM_XREF>^EHR_SYSTEM
OBR|1|<PROM_XREF>^EHR_SYSTEM||44249-1^PHQ-9 quick depression assessment panel^LN

Es wird genau eine Auftragsgruppe (ein ORC- und ein OBR-Segment) pro Nachricht unterstützt.
ORC-2 (Placer Order Number) und OBR-2 müssen byte-identisch sein, inklusive Namespace-Komponente (^EHR_SYSTEM).
Nur OBR-4.1 (Instrument-Code) wird an die Plattform übergeben. Die Zuordnung von Instrument-Code zu PROM-Workflow wird in den samedi-Praxiseinstellungen gepflegt, das Gateway pflegt keine eigene Mapping-Tabelle.
Der Patient bzw. Fall muss auf der Plattform bereits existieren (üblicherweise durch vorherige ADT-Onboarding). Ist die Referenz noch nicht auflösbar, antwortet die Plattform mit einer wiederholbaren Meldung und das Gateway sendet MSA|AE, damit das KIS den Auftrag erneut sendet.
Die Plattform dedupliziert anhand der Placer Order Number (ORC-2). Ein erneutes Senden derselben Nachricht ist gefahrlos (MSA|AA, kein zweiter Auftrag); das Gateway hält keinen eigenen Zustand.
Ein hl7_facility kann mehreren samedi-Accounts zugeordnet sein; der Auftrag wird dem Account zugestellt, der Patient bzw. Fall auflösen kann.

Unterstützte Felder

Feld	Required	Beschreibung
`MSH-6` (Receiving Facility)	`R`	Muss dem `hl7_facility` eines Accounts mit `orm_enabled = true` entsprechen.
`PID-3` (Patient Identifier List)	`C`	Externe Patienten-Referenz (xref) oder samedi Patienten-ID. Muss mit dem Onboarding-`ADT` übereinstimmen. Format wie in `ADT`/`SIU`.
`PV1-19` (Visit Number)	`C`	Fallnummer/Encounter-Referenz. Wird als `encounter_xref` an die Plattform übergeben.
`ORC-1` (Order Control)	`R`	Nur `NW` (New Order) wird akzeptiert.
`ORC-2` (Placer Order Number)	`R`	Auftragsnummer inkl. Namespace-Komponente (`ORC-2-2`). Wird verbatim übergeben und dient der Deduplizierung.
`OBR-2` (Placer Order Number)	`R`	Muss `ORC-2` exakt entsprechen (inkl. Namespace).
`OBR-4.1` (Universal Service Identifier)	`R`	Instrument-Code des PROM. Wird an die Plattform übergeben.

Mindestens eine Patienten- oder Fall-Referenz (PID-2/PID-3 oder PV1-19) muss vorhanden sein.

ACK-Verhalten

Das Gateway beantwortet jede Nachricht mit einem ACK. Das erste Feld des MSA-Segments zeigt das Ergebnis, das achte Feld des ERR-Segments enthält bei AE/AR einen lesbaren Grund.

MSA	Bedeutung	Beispielursachen
`AA`	Auftrag angenommen (oder identischer Replay)	gültige Nachricht, Patient/Fall vorhanden
`AE`	Temporärer Fehler – das KIS sollte erneut senden	Patient/Fall noch nicht gefunden (`patient_not_found`, `encounter_not_found`, `encounter_not_ready`, `case_not_found`), Plattform vorübergehend nicht erreichbar (5xx)
`AR`	Dauerhafte Ablehnung – erneutes Senden ändert nichts	siehe folgende Tabelle

Ablehnungen mit MSA|AR und zugehörigem ERR-Text:

Ursache	ERR-Text (Auszug)
Falscher Trigger Event (nicht `O01`)	`message not supported`
`ORC-1` ≠ `NW`	`unsupported ORC-1 order control`
`ORC-2` leer	`ORC-2 placer order number is empty`
`OBR-2` echot `ORC-2` nicht	`does not echo`
`OBR-4` Instrument-Code leer	`OBR-4 instrument code is empty`
Mehrere Auftragsgruppen	`multi-order ORM not supported`
Keine Patienten-/Fall-Referenz	`ORM contains no patient identifier`
Unbekannter Instrument-Code (Plattform)	Ablehnung durch die Plattform
`orm_enabled` nicht gesetzt	`ORM not enabled for any samedi account matching this facility`

Konfiguration

ORM-Verarbeitung ist standardmäßig deaktiviert und wird pro Account aktiviert:

[samedi.accounts.<name>]
hl7_facility = ["<FACILITY>"]
orm_enabled = true