Erstellen Sie eine Connect-Pipe
Ziel: Nachrichten von einem externen System empfangen, an ein Ziel weiterleiten und die erfolgreiche Zustellung nachweisen. Die Schnittstelle wird in Tiet · Connect → Network → Pipes erstellt, ohne dass ein Workflow erforderlich ist.
Verwenden Sie eine Connect-Pipe, wenn Sie einen einfachen Transport benötigen: Empfangen, optionales Transformieren, Zustellen. Wenn Sie mit Workflow-Knoten festlegen möchten, was mit jeder Nachricht geschieht, verwenden Sie stattdessen die Workflow-Route: Rezept: ADT zu FHIR.
Sie benötigen: die Berechtigung zum Anzeigen und Ändern von Connect-Kanälen, einen Connect-Server im Standalone-Modus (Standardeinstellung), ein Ziel für die Zustellung und eine Möglichkeit zum Senden einer Testnachricht. Diese Seite verwendet zwei Beispiele:
- HL7 über MLLP rein, HTTP raus. Der typische Krankenhausfall.
- Kafka rein, Datei raus. Ein zweiter Quell- und Zieltyp.
Hintergrundinformationen zu Modi, Gesundheit und Konnektoren finden Sie Tiet · Connect.
Beispiel 1: HL7 über MLLP zu einem HTTP-Endpunkt
Öffne den Builder
- Wählen Sie in der linken Navigation Tiet · Connect → Network und öffnen Sie dann Pipes.
- Klicken Sie auf New pipe. Der Editor öffnet sich mit sechs Schritten auf der linken Seite: Basics, Source, Processing, Destinations, Routing, Review. Ein Fortschrittszähler zeigt „n/5 Abschnitte fertig“ an.
Schritt 1: Grundlagen
| Feld | Beispiel | Anmerkungen |
|---|---|---|
| Channel name | Demo ADT to webhook | Erforderlich. Einzigartig innerhalb Ihrer Organisation. |
| Description | Synthetic ADT messages to a test webhook | Optional. |
| Tags | hl7, demo | Durch Kommas getrennt. |
| Enable on create | An | Standardmäßig aktiviert. |
Schritt 2: Quelle
Wählen Sie Type TCP (MLLP/HL7) (Gruppe Netzwerk). Die Felder:
| Feld | Beispiel | Anmerkungen |
|---|---|---|
| Bind Host | 0.0.0.0 | |
| Port | 2575 | Erforderlich. |
| Framing | MLLP | Wählen Sie MLLP. Raw TCP ist ein anderer, nicht HL7-fähiger Listener. |
| Delimiter | leer lassen | Nur unkomprimiertes TCP. |
Schritt 3: Verarbeitung
Lassen Sie die Liste leer. Die Seite zeigt „Noch keine Prozessoren – Nachrichten werden unverändert weitergeleitet.“ an. In diesem Beispiel wird der HL7-Text so weitergeleitet, wie er eintrifft.
Dieser Schritt bietet elf Schaltflächen unter Add a transformer or processor: Pipeline, Anonymizer, Filter, Tag Transformer, AI Inference, JavaScript, HL7 to FHIR, FHIR to HL7, XPath, JSONPath und Regex. Jede hinzugefügte Schaltfläche wird zu einer nummerierten Karte unter Pipeline order mit einem Aktivierungsschalter, einem Konfigurationsformular (oder einem JSON-Feld, falls kein bekanntes Formular existiert) und einer Liste On error (Stop on error, Skip on error, Fallback on error). Die Prozessoren werden von oben nach unten ausgeführt. Pipeline werden Sie aufgefordert, einen bereitgestellten Workflow auszuwählen. Bevor Sie sich auf diese Funktionen verlassen, lesen Sie bitte „HL7 zu FHIR: Was Sie wissen müssen“: Der Builder speichert die Karten, die Engine führt jedoch nur einige davon aus.
Schritt 4: Reiseziele
Klicken Sie auf die Liste Type von Destination 1 und wählen Sie HTTP / HTTPS. Die Felder:
| Feld | Beispiel | Anmerkungen |
|---|---|---|
| URL | https://webhook.example.org/hl7 | Erforderlich. Verwenden Sie einen Testempfänger, den Sie kontrollieren. |
| Method | POST | POST, PUT, PATCH oder GET. |
| Content-Type | text/plain | Der Standardwert ist application/json. HL7 v2 ist kein JSON, daher muss er festgelegt werden. |
| Timeout (ms) | 30000 | |
| Auth Type | none | basic, bearer oder api_key benötigen die übereinstimmenden Felder (Benutzername und Passwort, Bearer-Token, API-Key-Header und API-Key-Wert). |
| Idempotency Key / Idempotency Header | leer | Optional. Sendet einen Header (z. B. Idempotency-Key), damit ein Empfänger doppelte Neuzustellungen verwerfen kann. Ohne Header und ohne Schlüssel verwendet Connect einen Hash der Nutzdaten. |
Add destination fügt weitere Ziele hinzu. Jedes Ziel erhält jede Nachricht.
Schritt 5: Routing
Delivery route bietet zwei Möglichkeiten:
- Direct (Quelle → Ziel): Auf dieser Connect-Instanz verarbeitet. Wählen Sie dies für das Beispiel.
- On mesh (Speiche → Hub → Speiche): Wählen Sie eine Source spoke und eine Destination spoke. Ohne registrierte Speichen wird die Meldung angezeigt: „Es sind noch keine Speichen registriert. Registrieren Sie eine Speiche in der Mesh-Ansicht, um diesen Kanal über das Mesh zu routen.“
Die Connect-API speichert keine Spoke-Auswahlen, die über das Kanalformular gesendet werden. Der Server verwirft die Werte source_spoke_id und destination_spoke_id aus Erstellungs- und Aktualisierungsanfragen, da diese nur vom Hub-Routenendpunkt (Mesh-Token) gesetzt werden können. Die Auswahl von Spokes im Builder ändert die Route daher möglicherweise nicht. Überprüfen Sie die Route nach dem Speichern im Rohrinspektor oder in der Mesh-Ansicht, bevor Sie sich darauf verlassen.
Processing settings:
| Feld | Standard | Bedeutung |
|---|---|---|
| Max threads | 1 | Parallele Arbeiter für den Kanal. |
| Queue buffer size | 1000 | Größe der Kanalwarteschlange. Wenn diese voll ist, wird die Nachricht verworfen und mit dem Fehlercode Queue full markiert. |
| Preserve per-key order | aus | Beta. Hält Nachrichten mit demselben Schlüssel (HL7 PID-3, FHIR-Subjekt) threadübergreifend in der Reihenfolge ihres Eintreffens. Bei Aktivierung wird Ordering key source angezeigt; lassen Sie das Feld leer, um den Schlüssel aus der Nachricht abzuleiten. |
Bei Max threads über 1 und Preserve per-key order deaktiviert können zwei Nachrichten für denselben Patienten in beliebiger Reihenfolge angewendet werden. Für ADT-Datenverkehr sollte Max threads auf 1 belassen werden, oder die Reihenfolge kann aktiviert und getestet werden.
Dieser Schritt listet au ßerdem Umschalter (Store messages, Encrypt data, Export data, Remove content on complete), eine Gruppe Advanced mit Message storage mode, Clear global channel map on redeploy und FHIR batching (siehe unten) sowie vier Skriptfelder (Preprocessing script, Postprocessing script, Deploy script, Undeploy script) auf. Belassen Sie diese für dieses Beispiel auf ihren Standardeinstellungen.
Schritt 6: Überprüfung
Die Übersicht listet Kanal, Quelle, Verarbeitung (bei leerer Liste „Passthrough“), Ziele und Route auf, jeweils mit einer Schaltfläche zum Zurückspringen. Fehlt eine Angabe, erscheint eine Meldung: „Geben Sie einen Kanalnamen ein, um fortzufahren.“, „Wählen Sie einen Quellkonnektor.“ oder „Fügen Sie mindestens ein Ziel hinzu.“
Klicken Sie auf Create channel. Die Meldung lautet: „Kanal erstellt“.
Verlegen Sie die Rohrleitung
Die neue Pipe erscheint in „Pipes“ mit dem Status Ready: Sie existiert, ist aber noch nicht aktiv. Klicken Sie auf die Pipe und anschließend in der Fußzeile des Inspektors Resume Der Status ändert sich zu Deployed.
Im Schritt „Überprüfung“ heißt es, der Kanal werde „dem Mesh hinzugefügt und bereitgestellt“. In der Praxis wird er jedoch nur mit Create channel erstellt. Stellen Sie ihn mit Resume bereit.
Sende eine Testnachricht
Verwenden Sie die Simulations-CLI von tietai-simulation-service. Sie sendet ausschließlich synthetische Patienten.
sim-cli hl7 send --host <connect-host> --port 2575 --type ADT^A01 --count 1 --verbose
Die Optionen -H/--host app/cli/main.py Standardwert localhost), -p/--port, -t/--type (ADT^A01, ADT^A03, ADT^A04, ADT^A08, ORU^R01, ORM^O01), -n/--count, -r/--rate, -f/--file (eigene Datei; - ist stdin), -v/--verbose, --timeout (Sekunden, Standardwert 10) und --no-ack. Der Befehl sendet die Nachricht über MLLP und prüft die Empfangsbestätigung: AA oder CA gelten als Erfolg.
Der MLLP-Listener sendet seine AA-Bestätigung, sobald die Nachricht in die Kanalwarteschlange aufgenommen wurde. Er wartet nicht auf die Zustellung an das Ziel. Eine AA von Connect beweist nicht, dass das Ziel die Nachricht empfangen hat. Überprüfen Sie die Nachrichten der Pipe wie unten dargestellt.
Ergebnis prüfen
- Klicken Sie auf das Rohr, dann auf Messages. Es öffnet sich eine Schublade mit den Registerkarten In channel und Dead-letter, auf denen jeweils ein Zähler steht.
- Auf In channel sind die Statusfilter All, Sent, Buffered, Queued und Error. Das Suchfeld akzeptiert eine Nachrichten-ID oder einen Patientennamen. Die Liste wird alle 20 Sekunden aktualisiert.
- Wählen Sie Ihre Nachricht aus. Im Detailbereich wird der Status angezeigt: Route, Errors (falls vorhanden), Headers und Payload (Registerkarten pro Darstellungsart wie z. B. Rohdaten, Transformiert, Verarbeitet, Antwort).
Was Sie sehen sollten: eine Nachricht mit dem Status Sent und der gleiche HL7-Text, der an Ihrem Webhook ankommt.
| Status | Bedeutung |
|---|---|
| Received | Bei Ankunft eingelagert. |
| Sent | Es wurde von allen Reisezielen akzeptiert. |
| Buffered | Die Empfänger haben die Nachricht angenommen, aber mindestens einer hat sie nicht dauerhaft gespeichert. Der Status ändert sich, sobald der Empfänger die Nachricht bestätigt. Dies ist nicht dasselbe wie „Gesendet“. |
| Queued | Die Anfrage wird an den FHIR-Batcher übergeben (siehe FHIR-Batching unten) und wartet auf die Antwort des FHIR-Servers. Der Status ändert sich zu „Senden“ oder „Fehler“. |
| Error | Alle Ziele konnten nicht erreicht werden, die Warteschlange war voll oder der FHIR-Server hat einen Batch abgelehnt. |
Wenn eines von mehreren Zielen fehlschlägt, wird die Nachricht weiterhin als „Gesendet“ (oder „Zwischengepuffert“) angezeigt, und in der Fehlerliste steht „Teilerfolg: …“. Überprüfen Sie diese Liste, wenn Daten an einem Ziel fehlen. Die Liste Recent messages des Pipe-Inspektors zeigt die letzten sechs Einträge an.
Fehlerbehandlung
Bei einer fehlgeschlagenen Zustellung wird die Nachricht im Status Error angezeigt. Um alle Nachrichten anzuzeigen, öffnen Sie die Registerkarte Dead-letter (diese Pipeline) oder Tiet · Connect → Network → DLQ (alle Pipelines) im Menü.
- Standalone-Modus: Die Ansicht für unzustellbare Nachrichten ist schreibgeschützt. Es wird angezeigt: „Schreibgeschützt: Diese Connect-Instanz läuft im Standalone-Modus und kann unzustellbare Nachrichten weder wiedergeben noch verwerfen.“ Beheben Sie die Ursache und senden Sie die Nachricht anschließend erneut von der Quelle. Auf der Registerkarte In channel löscht die Taste Discard (dann Delete “) den Eintrag einer Nachricht.
- Hub-Modus: Wählen Sie einen toten Buchstaben aus und geben Sie Replay oder Discard mit Begründung an. Replay page versucht, jeden toten Buchstaben auf der Seite erneut abzurufen. In der DLQ-Konsole können Sie auch mehrere auswählen. Mit Expire old werden alte, aufgelöste oder verworfene Datensätze automatisch entfernt.
Häufige Fehler:
| Was Sie sehen | Ursache und Lösung |
|---|---|
| Rohr bleibt bei Ready | Es wurde erstellt, aber noch nicht bereitgestellt. Klicken Sie auf Resume. |
| Der Absender kann keine Verbindung herstellen. | Die Verbindung ist Ready oder pausiert, oder Port 2575 ist nicht erreichbar. Setzen Sie die Verbindung fort und überprüfen Sie den Netzwerkpfad. |
Nachricht Error, Text beginnt HTTP request failed with status | Die Zieladresse antwortete mit einem Statuscode ungleich 2xx. Der Antworttext ist im Text enthalten. Bitte korrigieren Sie die URL, die Anmeldeinformationen oder den Inhaltstyp. |
Nachricht Error, Text HTTP request failed: | Das Ziel konnte nicht erreicht werden (DNS, TLS, Zeitüberschreitung). |
Nachricht Error, Text beginnt FHIR server rejected the transaction oder BATCH_TIMEOUT | FHIR-Batching: Der Server hat den Batch abgelehnt oder nicht geantwortet. Lesen Sie die Fehlercodes im Text und überprüfen Sie die Bearer-Token-Eigenschaft. |
Nachricht Error, Text Queue full | Siehe Queue buffer size und Max threads. |
Nachricht Error, Text All destinations failed: ... | Das Präfix des Fehlers. Die nachfolgenden Namen geben an, welches Ziel nicht erreicht werden konnte. |
| Rohrbezeichnung Errors recorded oder High error share | Die Zähler werden seit ihrer Erstellung kumulativ angerechnet. Öffnen Messages → Error. |
Beispiel 2: Kafka in eine Datei
Dies zeigt eine zweite Quelle und ein zweites Ziel an und benötigt keinen HTTP-Empfänger.
- Grundlagen: Name
Demo Kafka to file. - Quelle: Type
Apache Kafka. Felder: Brokers (erforderlich, durch Komma getrennt, z. B.kafka.example.org:9092), Topic (erforderlich,sim.inbound), Consumer Group (tietai-connect). - Verarbeitung: leer.
- Ziele: Type
File System. Felder: Directory (erforderlich,/data/outgoing), Filename Pattern (msg_${timestamp}.txt), Append (aus), Create Dirs (ein), File Mode (0644). Das Verzeichnis befindet sich auf dem Connect-Server. - Routing: Direct. Review → Create channel, dann Resume.
- Senden Sie einen Testdatensatz:
sim-cli kafka send --bootstrap kafka.example.org:9092 --topic sim.inbound --format hl7v2 --count 3
--format ist hl7v2, fhir, raw oder auto; --key legt den Datensatzschlüssel fest (Standard: die Patienten-MRN). Öffnen Sie Messages → In channel: drei Nachrichten und drei Dateien in /data/outgoing.
HL7 zu FHIR: Was Sie wissen müssen
Der Builder hat im Verarbeitungsschritt den Eintrag HL7 to FHIR und den Zieltyp FHIR REST Folgendes bewirkt der Verbindungscode, geprüft in den channel_engine.go, internal/transformers/transformer.go, internal/connectors/http.go und fhir_batcher.go.
1. Der Prozessoreintrag. Der Builder ermöglicht das Hinzufügen einer Karte mit HL7 to FHIR und speichert diese in der Prozessorliste des Kanals. Die Engine führt sie jedoch nicht aus. Die Prozessorkette der Engine (initProcessorChain, processors.NewDefaultRegistry) kennt nur vier DICOM-Prozessoren: filter, anonymizer, tag-transformer und ai-inference und wendet diese ausschließlich auf DICOM-JSON-Inhalte an. Jeder andere Prozessortyp (einschließlich hl7_to_fhir, fhir_to_hl7, javascript, xpath, jsonpath, regex) führt dazu, dass die Kette nicht erstellt werden kann. Connect protokolliert daraufhin „Fehler beim Erstellen der Prozessorkette“ auf dem Server und überspringt die gesamte Kette, einschließlich der DICOM-Prozessoren in derselben Liste. Der Builder speichert außerdem tag_transformer und ai_inference mit Unterstrichen, die von der Registry ebenfalls nicht erkannt werden. Nur Pipeline (hydra_pipeline) wird auf seinem eigenen Pfad ausgeführt, und zwar nur dann, wenn auf dem Connect-Server HYDRA_API_URL festgelegt und CONNECT_AGENTIC_PROCESSORS_ENABLED nicht auf „false“ gesetzt ist. Die Engine führt die HL7-zu-FHIR-Konvertierung nur dann durch, wenn die Kanaleigenschaft transform_to_fhir den true hat (diese wird vom Connect-basierten HL7-Kanal festgelegt). Der Builder verfügt über kein Feld für diese Eigenschaft. Wenn Sie eine Konvertierung für einen Kanal benötigen, legen Sie die Eigenschaft über die Kanal-API fest oder verwenden Sie den Workflow-Pfad in Rezept: ADT zu FHIR. Für die Laborergebnisse von ORU^R01 wählt die auf HL7_ORU_TO_FHIR (mit transformer_options) gesetzte Eigenschaft transformer_type ein auftragsbezogenes Mapping aus, das ein Transaktionsbündel erzeugt und die Nachricht als fehlerhaft zurückweist, anstatt rohes HL7 weiterzuleiten. Testen Sie mit einer synthetischen Nachricht und lesen Sie den Tab Payload bevor Sie sich auf eine Konvertierung verlassen.
2. Der Bundle-Typ. Bei der Standardkonvertierung HL7_TO_FHIR enthält das erzeugte Bundle Einträge mit dem fullUrl type: "collection", aber keinen Eintrag mit request. Es handelt sich nicht um ein Transaktions-Bundle.
3. Das FHIR-REST-Ziel. FHIR REST ist der HTTP-Connector unter einem anderen Namen (fhir_rest entspricht HTTP). Er sendet den Nachrichtentext unverändert an FHIR Server URL mit der von Ihnen gewählten Methode Method (POST oder PUT) und an Content-Type: application/fhir+json, sofern Sie dies nicht überschreiben. Er wandelt kein Collection Bundle in eine Transaktion um. Ein FHIR-Server, der eine Transaktion oder einen Batch an seiner Basis-URL erwartet, lehnt ein Collection Bundle ab, und die Nachricht zeigt Error mit HTTP request failed with status ... und dem Text des Servers an.
4. FHIR-Batching. Aktivieren Sie in Schritt 5 die Option FHIR batching und setzen Sie den Wert auf FHIR server URL (ohne diese Einstellung ist das Batching wirkungslos). Felder: Batch size, Batch timeout (s), Max concurrent batches, FHIR server URL Wenn der Datentyp der Engine FHIR ist, werden Ressourcen gesammelt und als Transaktionsbündel an die entsprechende URL gesendet. Eine einzelne Ressource oder ein Eintrag in einem Sammlungsbündel wird zu einem Eintrag POST für seinen Ressourcentyp; ein Transaktionsbündel, dessen Einträge bereits request Einträge enthalten, wird unverändert Eintrag für Eintrag in die Warteschlange gestellt. Wenn das Größenfeld leer gelassen wird, werden die Standardwerte der Engine verwendet: 25 Ressourcen, 5 Sekunden, 20 gleichzeitige Batches. Der Batcher umgeht die Zielkonnektoren.
- Die Meldung zeigt den Queued an, bis der FHIR-Server antwortet. Eine 2xx-Antwort ändert den Status auf Sent. Eine Ablehnung oder ein Übertragungsfehler ändert den Status auf Error mit einem Text wie „FHIR-Server hat die Transaktion abgelehnt (HTTP 400): ...“. Wenn keine rechtzeitige Antwort eintrifft, markiert Connect die Meldung mit
BATCH_TIMEOUT(Batch-Timeout plus etwa eine Minute) als Error, und die Meldung kann erneut verarbeitet werden. - Die Authentifizierung ist kein Builder-Feld. Der Batcher sendet nur dann
Authorization: Bearer ..., wenn die Kanaleigenschaftfhir_bearer_token_env(der Name einer Umgebungsvariablen auf dem Connect-Server) oderfhir_bearer_tokengesetzt ist. Andernfalls protokolliert Connect eine Warnung und sendet die Transaktion ohne Authentifizierungsheader. Es werden immerX-Organization-ID,Content-TypeundAccept: application/fhir+jsongesendet.
Setzen Sie die Token-Eigenschaft über die Channel-API, bevor Sie die Batchverarbeitung auf einen FHIR-Server verweisen, der ein Token benötigt.
Wenn Sie heute eine verifizierte HL7-zu-FHIR-Route benötigen, erstellen Sie diese als Workflow mit den Knoten hl7-to-fhir und fhir-crud Diese Route sendet ein Transaktionsbündel. Siehe Rezept: ADT zu FHIR.
Ändern oder entfernen Sie eine Leitung
- Im Rohrleitungsinspektor öffnet Edit ein Seitenfenster für Name, Route, Ziele und Transformationen. Full editor öffnet dieselben sechs Schritte mit den gespeicherten Werten; die Schaltfläche „Speichern“ trägt die Nummer Save changes.
- Pause Deployments. Nichts hört zu, bis Sie Resume.
Was ist als Nächstes zu tun?
- Tiet · Connect: Modi, Gesundheit, Verbindungen und Grenzen.
- Rezept: ADT zu FHIR: der Workflow-Routine für die gleiche Eingabe.
Etwas unklar? Senden Sie Feedback zur Dokumentation per E-Mail..
