Ports, types et flux de données
Cette page explique comment les données circulent d'un nœud à l'autre dans un flux de travail : ce qu'est un port, comment le moteur remplit les entrées d'un nœud, quels types de ports peuvent être connectés, comment une condition supprime une branche et comment les espaces réservés {{NAME}} sont résolus. Chaque exemple ci-dessous a été exécuté sur le moteur réel avec des données synthétiques.
Vous connectez les nœuds dans le générateur de flux de travail. Pour trouver les ports d'un nœud particulier, ouvrez-le dans le générateur (Inspecteur, section Ports) ou dans le catalogue de nœuds.
Anatomie d'un ganglion
Un nœud comporte trois types d'éléments :
| Partie | Qu'est-ce que c'est | L'endroit où vous le définissez |
|---|---|---|
| Config | Paramètres indiquant au nœud l'action à effectuer (une opération, une URL, un seuil). Fixes pour chaque exécution. | Inspecteur, Node Settings |
| Input ports | Valeurs nommées que le nœud reçoit des nœuds en amont lors d'une exécution. Chaque port possède un type. | Tracez un bord dans le port |
| Output ports | Valeurs nommées produites par le nœud. Chaque port possède un type. | Tracez un bord à partir du port |
Sur le canevas, les noms des ports d'entrée sont listés à gauche de la carte du nœud et les noms des ports de sortie à droite. Chaque port est représenté par un point coloré (la couleur correspond au type de port). Survolez un point pour afficher <port name> · <type>.
La plupart des nœuds ont deux sorties en commun : result (la charge utile, généralement de type json) et success (une sortie de boolean). Voici quelques exemples tirés du catalogue :
| Identifiant du nœud | ports d'entrée (type) | ports de sortie (type) |
|---|---|---|
input | input (n'importe lequel) | output (n'importe lequel) |
condition | field (n'importe lequel), context (n'importe lequel) | true (json), false (json), condition_met (booléen), success (booléen) |
transform | input (json) | result (json), errors (json), error_count (nombre), success (booléen) |
hl7-to-fhir | hl7_message (texte) | result (json), success (booléen) |
fhir-crud | resource (json), resource_json (texte), resource_id (texte), bundle (fhir-bundle) | result (json), success (booléen) |
output | input (n'importe lequel) | result (json), success (booléen) |
Un bord relie un port à un port
Une arête est stockée sous la forme de quatre valeurs : nœud source, port source, nœud cible et port cible. Elle ne désigne aucun champ des données. Lors de l'exécution du flux de travail, le moteur copie le contenu du port source vers les entrées du nœud cible, en utilisant le nom de ce dernier. Si vous avez besoin d'un champ spécifique de cette valeur, le nœud récepteur doit l'extraire (voir Lecture des données en amont).
Si vous tracez une arête sans choisir de ports, le générateur enregistre les valeurs par défaut output (source) et input (cible).
Comment le moteur remplit les entrées d'un nœud
Avant l'exécution de chaque nœud, le moteur construit son initialisation inputs en examinant chaque arête qui y pointe. Trois règles s'appliquent, dans cet ordre de spécificité :
- Paire générique. Une arête du port
outputau portinputfusionne la totalité de la sortie du nœud source avec les entrées de la cible, clé par clé. Si la source a encapsulé sa charge utile dansresult, le moteur la désencapsule d'abord afin que la cible voie directement les clés internes.successest également transmis. - Paire nommée. Toute autre arête copie la valeur du port source vers le port d'entrée portant le nom de la cible :
inputs[target_port] = outputs[source_port]. - En cas de repli, utiliser
resultSi le port source nommé ne se trouve pas au niveau supérieur de la sortie de la source, le moteur le recherche dans l'objetresultde la source. (C'est pourquoi une arête provenant defhir_bundlefonctionne pour un nœud qui renvoie son bundle sousresult)
Les entrées d'exécution (par exemple les valeurs que vous donnez à Run with inputs) sont également copiées dans le inputs de chaque nœud avant que les sorties en amont ne soient ajoutées.
Fan-in : plusieurs bords convergent vers un seul port
Si plusieurs arêtes aboutissent au même port d'entrée via une paire nommée (règle 2 ou 3), les valeurs ne sont pas écrasées. Elles sont fusionnées :
- Si les deux valeurs sont des objets de résultat FHIR avec un
bundle, les tableauxbundle.entrysont concaténés et les valeurs numériquestotaletcountsont ajoutées. - Sinon, les valeurs sont regroupées dans une liste, dans l'ordre d'évaluation des arêtes. Deux nœuds d'entrée avec
{x: 1}et{y: 2}connectés deoutputà un port nomméfooont donnéfoo = [{x: 1}, {y: 2}].
Les arêtes utilisant la paire générique (output à input) ne sont pas combinées. Elles fusionnent les clés une à une dans les entrées ; ainsi, lorsque deux sources ont la même clé, l’arête évaluée en dernier est retenue. Les deux mêmes nœuds d’entrée connectés output à input ont donné {x: 1, y: 2, output: {y: 2}}.
Types de ports
Chaque port possède un type, représenté par un petit symbole dans la palette et par une infobulle sur le port. Les types présents dans le catalogue (198 nœuds) sont json, text, boolean, number, any, fhir-bundle, binary et string. Les règles de compatibilité définissent également les types fhir-resource, hl7-message, x12-message, dicom, ndjson, csv, xml et html.
Quels types se connectent
La règle repose sur une hiérarchie simple. Un sous-type est connecté à ses types parents, et la vérification est symétrique (la connexion est possible dans les deux sens). any est connecté à tout. Toute autre paire n'est connectée que si les deux ports ont exactement le même type.
| Une sortie de type | peut se connecter à une entrée de type |
|---|---|
any | chaque type |
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 | du même type, text, any |
Ce qui surprend les gens :
fhir-bundleetfhir-resourcene sont pas liés.textetjsonne sont pas liés. Il n'y a pas de conversion automatique. Insérez un nœud entre eux pour obtenir le type souhaité.- Les ports
booleanetnumberne se connectent qu'au même type ou àany. - Un type qui n'est pas dans la hiérarchie (le catalogue comporte quelques ports de type
string) se connecte uniquement au même type ou àany.
Là où la règle est appliquée
- Lors du tracé d'une arête, le système bloque la connexion entre deux ports dont les types sont connus et incompatibles. Si l'un des ports est inconnu du système (par exemple, un nom de port inexistant), la connexion est autorisée.
- Validation partielle. La validation du serveur calcule
port type mismatch: <source>.<port> (<type>) → <target>.<port> (<type>) — these port types cannot connectet suggère des entrées cibles acceptant le type, mais pour un flux de travail existant, il s'agit d'un avertissement et le bouton Validate de la barre d'outils n'affiche que les erreurs (Valid ou Invalid et une infobulle avec les messages d'erreur). Une incompatibilité de type ne fait donc pas virer le bouton au rouge. La validation ne signale pas un nom de port inexistant. - Lors de l'exécution, le moteur ne vérifie pas les types. Il copie les valeurs par nom de port. Une incompatibilité de type qui aurait échappé à la détection (par exemple, dans un flux de travail écrit en YAML) n'est pas bloquée par l'exécuteur.
Élagage des branches et nœuds ignorés
Un nœud condition sélectionne une branche. Il compare sa valeur field à compare_value et émet une liste interne de ports actifs : ["true"] ou ["false"]. L’exécuteur parcourt ensuite chaque autre nœud et applique une règle :
Un nœud est ignoré lorsque toutes ses arêtes entrantes sont inactives. Une arête est inactive lorsque son nœud source a lui-même été ignoré, ou lorsque son port source ne figure pas dans la liste des ports actifs de ce nœud. Un nœud sans arêtes entrantes n'est jamais ignoré.
Un nœud ignoré ne s'exécute pas et son statut est skipped (affiché comme Skipped dans le pied de page de sa fiche). L'ignorance se propage : un nœud dont le seul nœud en amont a été ignoré l'est également. Un nœud possédant au moins une arête entrante active s'exécute ; ainsi, un nœud de jonction alimenté par les deux branches continue de fonctionner même si l'une d'elles est supprimée.
Par défaut, les ports d'un nœud condition ne transportent qu'une petite charge utile : condition_met et un bloc result contenant branch, compare_value et field_value. Pour transmettre l'enregistrement original sur la branche choisie, définissez pass_through dans la configuration de la condition sur {target_name: input_key} : la valeur de l'entrée nommée input_key est copiée sur la branche sous target_name Dans l'exemple ci-dessous, il s'agit {record: context}, ce qui copie tout ce qui est arrivé sur le port context.
Exemple concret : triage des résultats de laboratoire
Ce flux de travail comprend un nœud input (defaults : patient_id test-patient-a, test potassium, value 4.2), un nœud jsonpath (Pick the value, path: value), un nœud condition (field: value, condition_type: greater_than, compare_value: 5.5, pass_through: {record: context}), deux nœuds transform en mode map (urgent et routine) qui construisent patient, test et value à partir de input.record.*, et un nœud output alimenté par les deux. Chaque arête utilise un port déclaré par le nœud. Il a été exécuté deux fois sur le moteur.
| Courir | condition ports actifs | urgent | routine | output | Ce que le nœud output a reçu sur son port input |
|---|---|---|---|---|---|
value = 4,2 | ["false"] | sauté | complété | complété | {patient: "test-patient-a", test: "potassium", value: 4.2} |
value = 6,1 | ["true"] | complété | sauté | complété | {patient: "test-patient-a", test: "potassium", value: 6.1} |
Les bords, par port :
| Bordure (port source vers port cible) | Ce qu'il contient |
|---|---|
input nœud output à jsonpath data | Le record {patient_id, test, value} |
jsonpath value à condition field | Le nombre seul (4,2 ou 6,1) |
input nœud output à condition context | On réécoute l'intégralité du disque, donc pass_through peut le porter. |
condition false (ou true) à la transformation input | {condition_met, result: {branch, compare_value, field_value}, record: {patient_id, test, value}} |
transformer result en output input | {patient, test, value} |
Le nœud urgent n'a ni entrée ni sortie lors de l'exécution 4.2 : il n'a jamais été exécuté. Un nœud alimenté uniquement par urgent (un nœud transform supplémentaire connecté au nœud result du nœud urgent) est également ignoré, et un nœud input sans arêtes entrantes est tout de même exécuté.
field sur un condition nomme la clé testée, mais rien ne permet de résoudre un chemin à l'intérieur de la valeur arrivant sur le port field. Connecter l'enregistrement directement à field échoue : le moteur transmet l'objet entier au nœud et celui-ci s'arrête à values must be numeric for > comparison. Placez un nœud qui extrait la valeur avant la porte (ici jsonpath) et acheminez l'enregistrement séparément via context Une chaîne numérique telle que "6.1" échoue également à la comparaison numérique. Le moteur accepte une connexion vers un port non déclaré par le nœud (une connexion générique output à input répartit l'enregistrement en clés de niveau supérieur), mais le canevas ne propose que les ports déclarés ; il est donc impossible de le dessiner manuellement.
Les opérateurs numériques nécessitent des nombres réels. Une chaîne numérique telle que "6.1" (provenant par exemple d'un champ texte) est interprétée comme une erreur (values must be numeric for > comparison). Le nœud ne convertit pas les chaînes de caractères en nombres.
Lecture des données en amont : la convention input.<field>
Un nœud transform en mode map reçoit ses données sous le nom du port auquel il est connecté. Dans l'exemple, l'arête se termine au port input du nœud routine, donc les entrées de ce nœud sont { input: { ... } } et les correspondances doivent commencer par input..
config:
transformation_type: map
mappings:
patient: input.patient_id
test: input.test
value: input.value
Sans le préfixe input. les champs mappés apparaissent sous la forme null. Le même chemin pointillé fonctionne pour les données imbriquées, par exemple input.data.first_name.
{{NAME}} espace réservé
Toute chaîne de caractères dans la configuration d'un nœud peut contenir {{NAME}}. Le moteur la remplace juste avant l'exécution du nœud. Les espaces réservés ne sont résolus que dans la configuration, et non dans les arêtes ou les données circulant entre les nœuds. Le moteur essaie ces sources dans cet ordre, et la première qui trouve le nom est retenue :
| Commande | Syntaxe | Résolution de |
|---|---|---|
| 1 | {{run.id}}, {{run.pipeline_id}}, {{run.pipeline_version}}, {{run.node_id}}, {{run.started_at}} | Informations sur l'exécution actuelle (également {{run.run_id}}, identique à run.id). |
| 2 | {{NAME}} pour une attestation | Le magasin d'identifiants par locataire, lorsque la plateforme en a un configuré pour votre organisation. |
| 3 | {{variable_name}} | Une variable non secrète du tiroir Ressources du flux de travail (onglet Variables). |
| 3 | {{connectors.<name>.<field>}} | Champ d'un connecteur défini dans le tiroir Ressources (onglet Connectors). <name> correspond au nom ou à l'identifiant du connecteur. |
| 3 | {{storage.<name>.<field>}} | Un champ d'une entrée de stockage (par exemple bucket ou prefix) de l'onglet Storage. |
| 4 | {{key}} | Valeur de premier niveau dans les entrées d'exécution propres au nœud (provenant d'un nœud en amont ou des entrées d'exécution). Seules les chaînes de caractères, les nombres et les booléens sont substitués ; les objets, les listes et la valeur nulle ne le sont pas. |
Une valeur de remplacement qui ne correspond à aucune valeur est laissée en place sous forme de texte littéral, par exemple {{MISSING}}. L'exécution ne s'arrête pas ; le texte littéral est envoyé à tout ce qui utilise la valeur.
Une variable marquée comme secrète n'est pas résolue par {{NAME}}. Dans le panneau Ressources, une variable dont l'icône de secret (œil) est activée est refusée par le résolveur d'espace réservé. Un en-tête écrit comme Bearer {{FHIR_TOKEN}} avec un secret FHIR_TOKEN est transmis au système cible sous la forme du texte littéral Bearer {{FHIR_TOKEN}} Les secrets sont résolus uniquement via le magasin d'informations d'identification par locataire (ordre 2). Utilisez une variable non secrète uniquement pour les valeurs qu'il est sûr d'exposer dans la définition du flux de travail (par exemple, une URL de base).
L'onglet Variables affiche également cinq « VARIABLES SYSTÈME » ({{pipeline_id}}, {{execution_id}}, {{user_id}}, {{organization_id}}, {{current_timestamp}}). Le code du moteur qui interprète les espaces réservés ne tient pas compte de ces noms. Utilisez plutôt {{run.pipeline_id}}, {{run.id}} et {{run.started_at}}.
Exemple fonctionnel : message HL7 vers FHIR
Un message synthétique ADT^A01 transmis par hl7-to-fhir a produit un objet result (type json) avec les clés suivantes : fhir_bundle, mapping_details, resource_count, resources, source_type, unmapped_segments et warnings. Les seuls ports de sortie du nœud sont result et success.
fhir_bundle.typevauttransaction. Chaque entrée comporterequest.methodPOSTeturn:uuid:URL complète.- Le dossier contenait un Patient (identifiant PID-3, nom, date de naissance, sexe) et une Rencontre (classe
IMP, statutin-progress, localisation PV1-3, référence du sujet). NK1 a été rapporté dansunmapped_segments. - Connecté au port
bundled'un nœudfhir-crudavecoperation: transaction, le paquet a été envoyé une fois à la basefhir_urlcommePOST /r4avecContent-Type: application/fhir+jsonet l'en-têteAuthorization: Bearer <auth_token>. - Dans un flux de travail YAML, une arête avec
source_port: fhir_bundlefonctionnait, grâce au repli versresult. Le canevas de construction ne propose que le portresultpour ce nœud.
Les types s'alignent : result est json et bundle est fhir-bundle, et json se connecte à fhir-bundle.
Quand quelque chose ne coule pas
| Symptôme | Cause | Réparer |
|---|---|---|
| L'exécution se termine comme achevée, mais un nœud affiche Skipped alors que vous vous attendiez à ce qu'il s'exécute. | Son interface entrante se trouve sur un port condition inactif, ou son nœud en amont a été ignoré. Une erreur de saisie dans le nom du port d'une interface provenant d'un nœud condition est considérée comme une inactivité : par exemple, une interface provenant d'un port maybe ne génère aucune erreur, l'exécution se termine et la cible est ignorée. | Ouvrez l'arête dans l'inspecteur et vérifiez le nom du port source. Un nœud condition possède les ports true et false. |
| Un nœud s'exécute, mais une valeur attendue est manquante. | Le nom du port source du périphérique n'existe pas sur le nœud source ; par conséquent, aucune donnée n'est copiée. Le moteur ne signale aucun port inconnu. | Vérifiez les noms des ports sur le nœud source (survolez un point de port), puis exécutez Debug step-by-step et ouvrez le nœud dans l'onglet STEP DEBUG pour voir ce qu'il a reçu. |
values must be numeric for > comparison | Une chaîne de caractères a été fournie à un opérateur numérique. | Veuillez fournir un nombre réel (un nombre JSON, différent de "6.1"). |
Les champs mappés dans un transform sont null. | Le mappage ne commence pas par le nom du port. | Utilisez input.<field> lorsque le bord se termine au port input. |
node a (input) failed: required field missing: patient_id | Le nœud input a required_fields et l'exécution n'en a pas fourni. | Indiquez-le dans Run with inputs, ou ajoutez une valeur par défaut. |
compilation failed: node release hl7-to-fihr@ is unavailable | L'identifiant du type de nœud est incorrect. | Utilisez l'identifiant exact du catalogue de nœuds. |
compilation failed: connection references non-existent target node: ghost | Une arête pointe vers un identifiant de nœud qui ne fait pas partie du flux de travail. | Supprimez le bord ou corrigez l'identifiant. |
compilation failed: failed to determine execution order: circular dependency detected: no nodes with zero in-degree | Le graphique possède un cycle. | Supprimez le bord qui ferme la boucle. |
node w (fhir-crud) validation failed: fhir_url is required | Un champ de configuration obligatoire est vide. | Remplissez-le dans l'inspecteur. |
Un en-tête ou une URL affiche le texte {{NAME}} au niveau du système de réception. | Le nom n'a pas pu être résolu ou la variable est secrète. | Créez-la comme une variable non secrète, ou utilisez le magasin d'informations d'identification par locataire pour les secrets. |
Limites et notes
- Les valeurs sont transférées par nom de port. Il n'y a pas de câblage au niveau des champs, pas de conversion automatique entre les types et pas de vérification de type à l'exécution.
- En interne, le moteur libère la copie de travail de la sortie d'un nœud une fois que tous les nœuds en aval l'ont lue. Cela ne modifie en rien le résultat de l'exécution : les résultats par nœud affichent toujours
inputsetoutputsde chaque nœud.
Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.