Ports, Typen und Datenfluss
Diese Seite erklärt, wie Daten in einem Workflow von einem Knoten zum nächsten fließen: Was ein Port ist, wie die Engine die Eingänge eines Knotens füllt, welche Porttypen verbunden werden können, wie eine Bedingung einen Zweig beschneidet und wie {{NAME}} Platzhalter aufgelöst werden. Alle folgenden Beispiele wurden mit synthetischen Daten auf der realen Engine ausgeführt.
Sie verbinden Knoten im Workflow-Builder. Um die Ports eines bestimmten Knotens zu finden, öffnen Sie ihn im Builder (Inspektor, Abschnitt Ports) oder im Knotenkatalog.
Anatomie eines Knotens
Ein Knotenpunkt enthält drei Arten von Elementen:
| Teil | Was es ist | Wo Sie es hinstellen |
|---|---|---|
| Config | Einstellungen, die dem Knoten mitteilen, was er tun soll (eine Operation, eine URL, ein Schwellenwert). Werden bei jedem Lauf festgelegt. | Inspektor, Node Settings |
| Input ports | Benannte Werte, die der Knoten während eines Laufs von vorgelagerten Knoten empfängt. Jeder Port hat einen Typ. | Zeichne eine Kante in den Port |
| Output ports | Benannte Werte, die der Knoten erzeugt. Jeder Port hat einen Typ. | Zeichne eine Kante aus dem Port heraus |
Auf der Arbeitsfläche werden die Namen der Eingangsports links und die der Ausgangsports rechts neben der Knotenkarte angezeigt. Jeder Port wird durch einen farbigen Punkt dargestellt (die Farbe entspricht dem Porttyp). Bewegen Sie den Mauszeiger über einen Punkt, um <port name> · <type> anzuzeigen.
Die meisten Knoten haben zwei gemeinsame Ausgänge: result (die Nutzlast, üblicherweise Typ json) und success (ein boolean). Einige Beispiele aus dem Katalog:
| Knoten-ID | Eingangsanschlüsse (Typ) | Ausgangsanschlüsse (Typ) |
|---|---|---|
input | input (beliebig) | output (beliebig) |
condition | field (beliebig), context (beliebig) | true (JSON), false (JSON), condition_met (Boolesch), success (Boolesch) |
transform | input (json) | result (JSON), errors (JSON), error_count (Zahl), success (Boolescher Wert) |
hl7-to-fhir | hl7_message (Text) | result (JSON), success (Boolescher Wert) |
fhir-crud | resource (json), resource_json (text), resource_id (text), bundle (fhir-bundle) | result (JSON), success (Boolescher Wert) |
output | input (beliebig) | result (JSON), success (Boolescher Wert) |
Eine Kante verbindet einen Port mit einem Port
Eine Kante wird als vier Werte gespeichert: Quellknoten, Quellport, Zielknoten und Zielport. Sie benennt kein Feld innerhalb der Daten. Beim Ausführen des Workflows kopiert die Engine den Inhalt des Quellports in die Eingänge des Zielknotens unter dessen Namen. Wird ein einzelnes Feld aus diesem Wert benötigt, muss der empfangende Knoten es extrahieren (siehe „Lesen von Upstream-Daten “).
Wenn Sie eine Kante zeichnen, ohne Ports auszuwählen, speichert der Builder die Standardwerte output (Quelle) und input (Ziel).
Wie die Engine die Eingänge eines Knotens füllt
Bevor jeder Knoten ausgeführt wird, erstellt die Engine dessen inputs, indem sie jede Kante betrachtet, die auf diesen Knoten verweist. Dabei gelten drei Regeln, und zwar in dieser Reihenfolge ihrer Spezifität:
- Generisches Paar. Eine Kante von Port
outputzu Portinputführt die gesamte Ausgabe des Quellknotens Schlüssel für Schlüssel in die Eingaben des Zielknotens ein. Falls die Quelle ihre Nutzdaten inresultverpackt hat, entpackt die Engine diese zuerst, sodass das Ziel die inneren Schlüssel direkt sieht.successwird ebenfalls weitergeleitet. - Benanntes Paar. Jede andere Kante kopiert den Wert des Quellports in den Eingangsport mit dem Namen des Ziels:
inputs[target_port] = outputs[source_port]. - Falls der benannte Quellport nicht auf der obersten Ebene der Quellausgabe liegt, sucht die Engine ihn innerhalb des Quellobjekts
result(Deshalb funktioniert eine Kante vonfhir_bundlefür einen Knotenresultder sein Bundle unterresultzurückgibt.)
Die Eingabewerte (z. B. die Werte, die Sie für Run with inputs angeben) werden ebenfalls in den Eingang inputs jedes Knotens kopiert, bevor die vorgelagerten Ausgänge hinzugefügt werden.
Fan-in: Mehrere Kanten werden in einen Anschluss zusammengeführt
Wenn mehrere Kanten über ein benanntes Paar (Regel 2 oder 3) am selben Eingangsport enden, werden die Werte nicht überschrieben, sondern zusammengeführt.
- Wenn beide Werte FHIR-Ergebnisobjekte mit einer
bundlesind, werden diebundle.entryArrays verkettet und die numerischen Wertetotalundcountaddiert. - Andernfalls werden die Werte in einer Liste in der Reihenfolge der Kantenauswertung gesammelt. Zwei Eingangsknoten mit den Werten
{x: 1}und{y: 2}die vonoutputzu einem Port mit der Bezeichnungfooverbunden sind, ergabenfoo = [{x: 1}, {y: 2}].
Kanten, die das generische Paar (output zu input) verwenden, werden nicht gesammelt. Sie werden Schlüssel für Schlüssel in die Eingänge integriert. Wenn zwei Quellen denselben Schlüssel tragen, gewinnt die zuletzt ausgewertete Kante. Die gleichen beiden Eingangsknoten, verbunden mit output und input ergaben {x: 1, y: 2, output: {y: 2}}.
Porttypen
Jeder Port hat einen Typ, der in der Palette als kleines Symbol und als Tooltip am Port angezeigt wird. Die im realen Katalog (198 Knoten) vorkommenden Typen sind json, text, boolean, number, any, fhir-bundle, binary und string. Die Kompatibilitätsregeln definieren zusätzlich fhir-resource, hl7-message, x12-message, dicom, ndjson, csv, xml und html.
Welche Typen verbinden
Die Regel ist eine kleine Hierarchie. Ein Subtyp verbindet sich mit seinen übergeordneten Typen, und die Prüfung ist symmetrisch (Verbindungen sind in beide Richtungen möglich). any verbindet sich mit allem. Jedes andere Paar verbindet sich nur dann, wenn beide Ports exakt denselben Typ haben.
| Eine Ausgabe vom Typ | kann mit einem Eingang vom Typ verbunden werden |
|---|---|
any | jede Art |
json | json, fhir-bundle, fhir-resource, hl7-message, ndjson, any |
text | text, hl7-message, x12-message, ndjson, csv, xml, html, any |
number | number, any |
boolean | boolean, any |
binary | binary, dicom, any |
fhir-bundle | fhir-bundle, json, any |
fhir-resource | fhir-resource, json, any |
hl7-message | hl7-message, json, text, any |
x12-message | x12-message, text, any |
dicom | dicom, binary, any |
ndjson | ndjson, json, text, any |
csv, xml, html | vom gleichen Typ, text, any |
Dinge, die die Leute überraschen:
fhir-bundleundfhir-resourcesind nicht miteinander verbunden.textundjsonsind nicht miteinander verbunden. Es findet keine automatische Konvertierung statt. Fügen Sie einen Knoten dazwischen ein, der den benötigten Typ erzeugt.- Die Ports
booleanundnumberkönnen nur mit Geräten desselben Typs oder mitanyverbunden werden. - Ein Typ, der nicht in der Hierarchie vorhanden ist (der Katalog hat einige Ports vom Typ
string), verbindet sich nur mit demselben Typ oder mitany.
Wo die Regel durchgesetzt wird
- Während Sie eine Kante zeichnen, blockiert der Builder eine Verbindung zwischen zwei Ports, deren Typen bekannt, aber inkompatibel sind. Ist einer der Ports dem Builder unbekannt (z. B. aufgrund eines nicht existierenden Portnamens), wird die Verbindung zugelassen.
- Validierung (teilweise). Die Servervalidierung berechnet zwar
port type mismatch: <source>.<port> (<type>) → <target>.<port> (<type>) — these port types cannot connectund schlägt Zieleingaben vor, die den Typ akzeptieren, aber für einen bestehenden Workflow ist dies eine Warnung, und die Schaltfläche Validate in der Symbolleiste zeigt nur Fehler an (Valid oder Invalid mit einem Tooltip der Fehlermeldungen). Ein Typenkonflikt führt daher nicht dazu, dass die Schaltfläche rot wird. Die Validierung markiert keinen nicht existierenden Portnamen. - Zur Laufzeit prüft die Engine keine Typen. Sie kopiert Werte anhand des Portnamens. Ein durchgerutschter Typenkonflikt (beispielsweise in einem als YAML geschriebenen Workflow) wird vom Executor nicht behoben.
Zweigbeschneidung und übersprungene Knoten
Ein condition Knoten wählt einen Zweig aus. Er vergleicht seinen field mit dem Wert compare_value und gibt eine interne Liste aktiver Ports aus: ["true"] oder ["false"] Der Executor durchläuft dann jeden zweiten Knoten und wendet eine Regel an:
Ein Knoten wird übersprungen, wenn alle seine eingehenden Kanten inaktiv sind. Eine Kante ist inaktiv, wenn ihr Quellknoten selbst übersprungen wurde oder wenn ihr Quellport nicht in der Liste der aktiven Ports dieses Quellknotens enthalten ist. Ein Knoten ohne eingehende Kanten wird niemals übersprungen.
Ein übersprungener Knoten wird nicht ausgeführt und hat den Status skipped (in der Fußzeile der Knotenkarte als Skipped angezeigt). Das Überspringen wirkt sich aus: Ein Knoten, dessen einziger vorgelagerter Knoten übersprungen wurde, wird ebenfalls übersprungen. Ein Knoten mit mindestens einer aktiven eingehenden Kante wird ausgeführt; daher wird ein Knoten, der von beiden Zweigen gespeist wird, auch dann noch ausgeführt, wenn ein Zweig entfernt wird.
Die Ports eines condition Knotens übertragen standardmäßig nur eine geringe Nutzlast: condition_met und ein result Block mit branch, compare_value und field_value Um den ursprünglichen Datensatz an den gewählten Zweig weiterzuleiten, setzen Sie pass_through in der Konfiguration der Bedingung auf {target_name: input_key}: Der Wert des Eingangs mit der Bezeichnung input_key wird auf den Zweig unter target_name kopiert. Im folgenden Beispiel ist dies {record: context}, wodurch der Wert kopiert wird, der an Port context eingegangen ist.
Beispielrechnung: Triage von Laborergebnissen
Dieser Workflow besteht aus einem input Knoten (defaults: patient_id test-patient-a, test potassium, value 4.2), einem jsonpath Knoten (Pick the value, path: value), einem condition Knoten (field: value, condition_type: greater_than, compare_value: 5.5, pass_through: {record: context}), zwei transform Knoten im map Modus (urgent und routine), die patient, test und value aus input.record.* erzeugen, und einem output -Knoten, der von beiden gespeist wird. Jede Kante verwendet einen vom Knoten deklarierten Port. Der Workflow wurde zweimal auf der Engine ausgeführt.
| Laufen | condition aktive Ports | urgent | routine | output | Was der Knoten output an seinem Port input empfangen hat |
|---|---|---|---|---|---|
value = 4,2 | ["false"] | übersprungen | vollendet | vollendet | {patient: "test-patient-a", test: "potassium", value: 4.2} |
value = 6,1 | ["true"] | vollendet | übersprungen | vollendet | {patient: "test-patient-a", test: "potassium", value: 6.1} |
Die Ränder, nach Hafen:
| Edge (Quellport zu Zielport) | Was es mit sich trägt |
|---|---|
input Knoten output bis jsonpath data | Der Rekord {patient_id, test, value} |
jsonpath value bis condition field | Die Zahl allein (4,2 oder 6,1) |
input Knoten output bis condition context | Die gesamte Aufzeichnung nochmal, damit pass_through es tragen kann |
condition false (oder true) zur Transformation input | {condition_met, result: {branch, compare_value, field_value}, record: {patient_id, test, value}} |
result in output umwandeln input | {patient, test, value} |
Der Knoten urgent hat im 4.2-Lauf weder Eingänge noch Ausgänge und wird daher nie ausgeführt. Ein Knoten, der nur von urgent gespeist wird (eine zusätzliche transform die mit der result von urgent verbunden ist), wird ebenfalls übersprungen, während ein Knoten input ohne eingehende Kanten weiterhin ausgeführt wird.
field auf einer condition benennt den zu testenden Schlüssel, aber es lässt sich kein Pfad innerhalb des Werts auflösen, der am Port field ankommt. Das direkte Verbinden des Datensatzes mit field schlägt fehl: Die Engine übergibt dem Knoten das gesamte Objekt, und dieser stoppt bei values must be numeric for > comparison. Platzieren Sie einen Knoten, der den Wert extrahiert, vor dem Gate (hier jsonpath) und übertragen Sie den Datensatz separat über context. Auch eine numerische Zeichenkette wie "6.1" führt zu einem Fehler beim numerischen Vergleich. Die Engine akzeptiert zwar eine Kante zu einem Port, den der Knoten nicht deklariert (eine generische Kante output nach input verteilt den Datensatz auf Schlüssel der obersten Ebene), aber die Zeichenfläche bietet nur deklarierte Ports, sodass Sie diese nicht manuell zeichnen können.
Numerische Operatoren benötigen reelle Zahlen. Eine numerische Zeichenkette wie "6.1" (beispielsweise aus einem Textfeld) wird nicht als values must be numeric for > comparison interpretiert. Der Knoten wandelt keine Zeichenketten in Zahlen um.
Lesen von Upstream-Daten: die input.<field> Konvention
Ein transform Knoten im map Modus empfängt seine Daten unter dem Namen des Ports, mit dem er verbunden ist. Im Beispiel endet die Kante an Port input von routine, daher sind die Eingänge des Knotens { input: { ... } } und die Zuordnungen müssen mit input. beginnen.
config:
transformation_type: map
mappings:
patient: input.patient_id
test: input.test
value: input.value
Ohne das Präfix input. werden die zugeordneten Felder als null ausgegeben. Derselbe gepunktete Pfad funktioniert auch für verschachtelte Daten, zum Beispiel input.data.first_name.
{{NAME}} Platzhalter
Jede Zeichenkette in der Konfiguration eines Knotens kann {{NAME}} enthalten. Die Engine ersetzt diese kurz vor der Ausführung des Knotens. Platzhalter werden nur in der Konfiguration aufgelöst, nicht in Kanten oder Daten, die zwischen Knoten fließen. Die Engine versucht diese Quellen in der folgenden Reihenfolge, und die erste, die den Namen kennt, gewinnt:
| Befehl | Syntax | Entschließt sich zu |
|---|---|---|
| 1 | {{run.id}}, {{run.pipeline_id}}, {{run.pipeline_version}}, {{run.node_id}}, {{run.started_at}} | Fakten zum aktuellen Lauf (auch {{run.run_id}}, gleich wie run.id). |
| 2 | {{NAME}} für eine Berechtigung | Der mandantenspezifische Anmeldeinformationsspeicher, sofern die Plattform einen solchen für Ihre Organisation konfiguriert hat. |
| 3 | {{variable_name}} | Eine nicht geheime Variable aus dem Ressourcenbereich des Workflows (Registerkarte Variables). |
| 3 | {{connectors.<name>.<field>}} | Ein Feld eines im Ressourcenmenü (Registerkarte Connectors) definierten Konnektors. <name> ist der Name oder die ID des Konnektors. |
| 3 | {{storage.<name>.<field>}} | Ein Feld eines Speichereintrags (z. B. bucket oder prefix) aus der Registerkarte Storage. |
| 4 | {{key}} | Ein Wert der obersten Ebene in den Laufzeit-Eingaben des Knotens (von einem übergeordneten Knoten oder den Laufzeit-Eingaben). Nur Zeichenketten, Zahlen und boolesche Werte werden ersetzt; Objekte, Listen und Nullwerte nicht. |
Ein Platzhalter, der nicht aufgelöst wird, bleibt als Literaltext erhalten, beispielsweise {{MISSING}}. Die Ausführung wird nicht gestoppt; der Literaltext wird an die Stelle gesendet, die den Wert verwendet.
Eine als geheim gekennzeichnete Variable wird nicht durch {{NAME}} aufgelöst. Im Ressourcen-Drawer wird eine Variable, bei der das Symbol für geheime Daten (Auge) aktiviert ist, vom Platzhalter-Resolver abgelehnt. Ein Header, der als Bearer {{FHIR_TOKEN}} mit einem geheimen Wert FHIR_TOKEN geschrieben ist, erreicht das Zielsystem als Literaltext Bearer {{FHIR_TOKEN}}. Geheimnisse werden nur über den mandantenspezifischen Anmeldeinformationsspeicher aufgelöst (Reihenfolge 2). Verwenden Sie eine nicht geheime Variable nur für Werte, die in der Workflow-Definition sicher offengelegt werden können (z. B. eine Basis-URL).
Im Register „Variablen“ werden außerdem fünf „SYSTEMVARIABLEN“ ({{pipeline_id}}, {{execution_id}}, {{user_id}}, {{organization_id}}, {{current_timestamp}}) aufgeführt. Der Engine-Code, der Platzhalter auflöst, liest diese Namen nicht. Verwenden Sie stattdessen {{run.pipeline_id}}, {{run.id}} und {{run.started_at}}.
Beispielrechnung: HL7-Nachricht an FHIR
Eine synthetische ADT^A01-Nachricht, die über Port hl7-to-fhir geleitet wurde, erzeugte ein Objekt result (Typ json) mit den Schlüsseln fhir_bundle, mapping_details, resource_count, resources, source_type, unmapped_segments und warnings. Die einzigen Ausgabeports des Knotens sind result und success.
fhir_bundle.typeisttransaction. Jeder Eintrag hatrequest.methodPOSToderurn:uuid:vollständige URL.- Das Datenpaket enthielt einen Patienten (Identifikator aus PID-3, Name, Geburtsdatum, Geschlecht) und einen Behandlungsfall (Klasse
IMP, Statusin-progress, Ort aus PV1-3, Patientenreferenz). NK1 wurde inunmapped_segmentsberichtet. - Das Bündel wurde an den Port
bundleeines Knotensfhir-crudmitoperation: transactionangeschlossen und einmal an die Basisfhir_urlalsPOST /r4mitContent-Type: application/fhir+jsonund dem HeaderAuthorization: Bearer <auth_token>gesendet. - In einem YAML-Workflow funktionierte eine Kante mit
source_port: fhir_bundle, da aufresultzurückgegriffen wurde. Die Builder-Oberfläche bietet für diesen Knoten nur den Portresultan.
Die Typen passen zusammen: result ist json und bundle ist fhir-bundle, und json ist mit fhir-bundle verbunden.
Wenn etwas nicht fließt
| Symptom | Ursache | Fix |
|---|---|---|
| Der Lauf wird als abgeschlossen markiert, aber ein Knoten zeigt Skipped an, obwohl Sie erwartet haben, dass er ausgeführt wird. | Die eingehende Verbindung befindet sich an einem inaktiven Port condition oder der vorgelagerte Knoten wurde übersprungen. Ein falsch geschriebener Portname an einer Verbindung von einem Knoten condition wird als inaktiv gewertet: Beispielsweise führt eine Verbindung von Port maybe zu keinem Fehler, der Lauf wird abgeschlossen und das Ziel wird übersprungen. | Öffnen Sie die Kante im Inspektor und überprüfen Sie den Quellportnamen. Ein condition Knoten hat die Ports true und false. |
| Ein Knoten wird ausgeführt, aber ein erwarteter Wert fehlt. | Der Quellportname des Edge-Knotens existiert nicht auf dem Quellknoten, daher wird nichts kopiert. Die Engine meldet keinen unbekannten Port. | Überprüfen Sie die Portnamen auf dem Quellknoten (fahren Sie mit der Maus über einen Portpunkt), führen Sie dann Debug step-by-step aus und öffnen Sie den Knoten im Tab STEP DEBUG, um zu sehen, was er empfangen hat. |
values must be numeric for > comparison | Einem numerischen Operator wurde eine Zeichenkette übergeben. | Geben Sie eine gültige Zahl an (eine JSON-Zahl, nicht "6.1"). |
Zugeordnete Felder in einer transform sind null. | Die Zuordnung beginnt nicht mit dem Portnamen. | Verwenden Sie input.<field> wenn die Kante an Port input endet. |
node a (input) failed: required field missing: patient_id | Der Knoten input hat den required_fields, der Lauf lieferte jedoch keinen. | Geben Sie es in Run with inputs an oder fügen Sie einen Standardwert hinzu. |
compilation failed: node release hl7-to-fihr@ is unavailable | Die Knotentyp-ID ist falsch. | Verwenden Sie die exakte ID aus dem Knotenkatalog. |
compilation failed: connection references non-existent target node: ghost | Eine Kante verweist auf eine Knoten-ID, die nicht im Workflow enthalten ist. | Entferne den Rand oder korrigiere die ID. |
compilation failed: failed to determine execution order: circular dependency detected: no nodes with zero in-degree | Der Graph enthält einen Zyklus. | Entferne die Kante, die die Schleife schließt. |
node w (fhir-crud) validation failed: fhir_url is required | Ein erforderliches Konfigurationsfeld ist leer. | Füllen Sie es im Inspektionsformular aus. |
Im Header oder in der URL wird dem empfangenden System der Text {{NAME}} angezeigt. | Der Name konnte nicht aufgelöst werden, oder die Variable ist geheim. | Erstellen Sie es als nicht geheime Variable oder verwenden Sie den mandantenspezifischen Anmeldeinformationsspeicher für Geheimnisse. |
Grenzwerte und Anmerkungen
- Die Werte werden über den Portnamen übertragen. Es gibt keine Feldverdrahtung, keine automatische Konvertierung zwischen Typen und keine Typüberprüfung zur Laufzeit.
- Intern gibt die Engine die Arbeitskopie der Ausgabe eines Knotens frei, sobald jeder nachgelagerte Knoten sie gelesen hat. Dies ändert nichts am Ausführungsergebnis: Die Ergebnisse pro Knoten listen weiterhin die Werte
inputsundoutputsjedes Knotens auf.
Etwas unklar? Senden Sie Feedback zur Dokumentation per E-Mail..