Aller au contenu principal

Créez n'importe quel flux de travail

Un flux de travail (ou pipeline) est un graphe de nœuds. Les données arrivent à une extrémité, chaque nœud effectue une tâche et transmet son résultat au nœud suivant, et le dernier nœud produit le résultat final : un enregistrement, un message ou un rapport. Ce guide présente une méthode applicable à tout flux de travail, ainsi que les modèles de contrôle de flux à combiner pour le construire. Chaque modèle ci-dessous a été testé sur le moteur réel avec des données synthétiques, et les résultats affichés correspondent aux données obtenues.

Comment ce guide s'intègre-t-il aux autres ?

Un workflow est-il l'outil adéquat ?​

Vous avez besoinUtiliser
Une séquence fixe d'étapes avec des embranchements, identique à chaque fois, que vous pouvez tester et répéter.A workflow (ce guide)
Un assistant doté d'outils qui décide lui-même de ce qu'il faut appelerUn agent
Plusieurs étapes de modélisation avec rôles, routage, boucles de révision et un journal d'audit de chaque inviteUn graphe d'agents

Un flux de travail peut appeler des agents comme étape (le nœud agent-executor), vous pouvez donc les mélanger : une infrastructure fixe autour d'un modèle qui effectue le raisonnement.

La méthode​

La boucle à répéter : définir la tâche, connecter les nœuds, valider, tester, enregistrer une version, déployer et surveiller. En cas d’échec d’un test, retour à la connexion.

1. Définir le poste​

Avant d'ouvrir l'éditeur, notez cinq éléments. La plupart des bugs de flux de travail proviennent du fait d'en négliger un seul.

QuestionExemple (tri des résultats de laboratoire)
Comment cela commence-t-il ?Quelqu'un effectue le test avec un résultat de laboratoire.
Quelles sont les données entrantes, avec quels champs et quels types ?patient_id (texte), test (texte), value (un nombre).
Quelles décisions prend-il ?value est-il supérieur à 5,5 ?
Quelles feuilles, et où vont-elles ?Enregistrement important ou enregistrement de routine ; cet exercice n’envoie aucune notification.
Que se passe-t-il lorsqu'une étape échoue, et qui le constate ?L'exécution échoue et affiche Tiet · Studio → Workflows → Monitor.

2. Choisissez comment cela commence​

Le premier nœud détermine le démarrage du flux de travail. Choisissez celui qui correspond à la tâche.

CommencerNœudCe dont il a besoinUtilisez-le pour
Run by hand or APIinputdefaults (ou data) et required_fieldsTout ce que vous démarrez vous-même, avec des valeurs allant de Run with inputs à l'API
On a timerschedulerschedule_type (interval, once ou daily), interval_seconds, execute_at, time_of_dayTâches récurrentes. Pour une expression cron, choisissez Schedule dans le menu Exécuter (il propose des préréglages cron et une expression personnalisée et ajoute le nœud de déclenchement), ou utilisez Tiet · Studio → Workflows → Monitor → Schedules (voir Options d'exécution).
An HTTP callapi-webhookport (9090), listen_path, auth_mode (none, header_secret, hmac_sha256), webhook_secretUn autre système vous avertit
A FHIR subscriptionfhir-webhookfilter_resource_type, filter_eventRéagir aux modifications des ressources FHIR
An HL7 messagehl7-listenerlisten_port (2575), filtres sur le type de message, l'événement, l'application d'envoi et l'installationInterfaces hospitalières ; voir la recette ADT
Generic eventtriggertype (manual, webhook, schedule, condition, event)Quand aucune des réponses ci-dessus ne convient

Le port output du nœud input transporte l'enregistrement complet, permettant ainsi au nœud suivant de lire chaque champ.

3. Créez-le dans l'éditeur​

  1. Ouvrez Tiet · Studio → Workflows et choisissez New Workflow. Un éditeur vierge s'ouvre dans un onglet.
  2. Dans le panneau de gauche, sélectionnez Palette. Recherchez par nom, identifiant, catégorie, description ou type de port (la zone de texte indique « Rechercher par nom, type, port, standard… »), ou développez une catégorie. Faites glisser le nœud sur le canevas.
  3. Sélectionnez un nœud. Le Inspector à droite indique ses paramètres (Node Settings) et (Ports). Renseignez les champs obligatoires (marqués d'un astérisque rouge). Les paramètres sont répartis en onglets, tels que Basic et Advanced. La manière dont un paramètre est saisi dépend de son type : champs de texte et de nombre ; listes déroulantes pour les choix fixes ; interrupteurs marche/arrêt ; un champ de texte JSON pour les paramètres json et any (il devient rouge et conserve votre texte en texte brut jusqu’à son analyse) ; une liste avec Add item pour les tableaux tels que required_fields ; et, pour transform Mappings, des lignes avec Target et Source champs (plus Transform et Default lorsque le nœud les propose) ajoutés avec Add field.
  4. Tracez une arête d'un port de sortie (côté droit d'un nœud) vers un port d'entrée (côté gauche) du nœud suivant.
  5. Placez les valeurs que vous réutilisez (une URL de base, un seuil) dans Resources (barre d'outils), sur l'onglet Variables, et référencez-les comme {{name}}. Le même tiroir comporte Connectors, Storage et Test Data onglets.

Le flux de travail de triage des résultats de laboratoire dans l'éditeur : un nœud d'entrée, un nœud jsonpath qui sélectionne la valeur, un nœud de condition avec des ports vrai et faux, deux nœuds de transformation et un nœud de sortie.

La barre d'outils, de gauche à droite : commandes de zoom et de mise en page, Resources, Validate, Save, le bouton Test Live le sélecteur d'environnement Run in, Run (avec un menu fléché) et Deploy. Les onglets du panneau de droite sont Inspector, Assistant, Diff, Docs et API, et le commutateur Routing (Smart ou Curved) et AI Assistant se trouvent en haut à droite du canevas.

Sélectionnez un nœud pour voir exactement ce qu'il accepte et produit :

4. Câblez correctement les données.​

Cinq règles permettent de résoudre la plupart des problèmes. La page relative aux ports explique chacune d'elles à l'aide d'exemples.

  1. Une arête relie un port à un autre port, et non un champ. Si vous avez besoin d'un champ, un nœud intermédiaire doit le récupérer (par exemple, le nœud jsonpath, dont le port value contient le champ extrait). Dans l'éditeur, vous ne pouvez tracer des arêtes qu'entre les ports déclarés par un nœud ; vérifiez donc d'abord les ports dans l'inspecteur.
  2. En mode transform en map, les données en amont sont lues sous le nom du port auquel elles sont connectées ; leurs correspondances commencent donc par input. (par exemple input.patient_id). Sans préfixe, les champs sont vides.
  3. Un nœud condition teste la valeur sur son port field et ne transmet que le résultat de la comparaison. Le port field doit transporter le nombre lui-même, et non un enregistrement le contenant (un enregistrement provoque une erreur avec le port values must be numeric for > comparison). Pour transmettre l'enregistrement sur la branche choisie, connectez-le au port context et nommez-le dans le pass_through.
  4. Les comparaisons numériques nécessitent des nombres. Le texte "6.1" n'est pas un nombre et échoue avec values must be numeric for > comparison.
  5. Une variable secrète n'est pas remplacée par {{name}} Elle est transmise telle quelle à sa destination. Conservez les informations d'identification secrètes dans le gestionnaire de clés et n'utilisez les variables que pour les valeurs qu'il est sûr de voir dans le flux de travail.
Une erreur de frappe dans le nom du port ne provoque aucune erreur.

Si une arête utilise un port inexistant sur le nœud source, l'exécution se termine tout de même par un résultat de completed et le nœud cible affiche silencieusement skipped. Après chaque exécution, vérifiez la présence de nœuds ignorés et assurez-vous que chacun d'eux est bien attendu.

5. Tester, puis tester à nouveau​

OutilCe que cela vous dit
ValidateCe module vérifie le flux de travail avant son exécution. Il ne signale que les erreurs. Il ne signale pas les noms de port incorrects, ni les incompatibilités de types de ports, et ne les affiche pas en rouge.
Run with inputsFonctionne avec des valeurs que vous saisissez au format JSON. Les nombres doivent être des nombres JSON.
Sélecteur Run inSélectionne l'environnement d'exécution. Un environnement autorisant les brouillons exécute le contenu de l'éditeur ; tout autre environnement n'exécute que le contenu qui y a été déployé, et le serveur refuse le reste.
Live/Test basculeLe bouton affiche Live (connecteurs réels) ou Test (fixations). En mode Test les fixations et les substitutions d'entrée sont appliquées afin que les nœuds utilisent des données prédéfinies au lieu d'attendre des événements réels. L'option Dry run du menu Exécuter est intitulée « Exécuter en mode test », mais son fonctionnement est identique à celui de l'option Run ; elle suit l'état du commutateur, il est donc conseillé de passer d'abord à l'option Test Attention : aucune de ces options n'empêche un effet secondaire réel, tel qu'un appel téléphonique.
Debug step-by-stepFaites une pause à chaque nœud. Cliquez avec le bouton droit sur un nœud et choisissez Inspect Data, ou sélectionnez-le et ouvrez l'onglet Diff, pour voir les données d'entrée et de sortie.
EXECUTION LOG, STEP DEBUG, TRACEPanneau inférieur : état par nœud, données et arborescence des étendues de l’exécution.

La Run on mesh est toujours affichée mais désactivée (« Activer l'option Runs-on » d'un nœud) jusqu'à ce qu'au moins un nœud ait la valeur Runs on (placement) ; voir Run on mesh.

Testez les limites de vos données d'entrée, et pas seulement le centre : la plus petite valeur, un champ manquant, une valeur exactement égale à un seuil.

6. Enregistrez une version et publiez-la.​

Save (Ctrl/Cmd+S) ouvre le Save New Version, qui suggère le numéro de version suivant ; chaque enregistrement correspond à une nouvelle version. Enregistrez une fois avant la première exécution : Run, Run with inputs, Dry run et Deploy nécessitent un flux de travail préalablement enregistré, puis enregistrent vos modifications actuelles en premier (sans invite de version). Le menu Deploy affiche une entrée, Deploy vN to <environment>, pour chaque environnement supplémentaire, ainsi que Export as JSON et Export as YAML ; les options Activate (activer la planification, activer le déclencheur), « push » et « historique des déploiements » sont désactivées. Prenez connaissance des fonctionnalités et limitations de l’option Deploy et consultez la section « Environnements et promotion » avant de l’utiliser pour un déploiement contrôlé.

Après la sortie, la montre fonctionne en Tiet · Studio → Workflows → Monitor.

Modèles de flux de contrôle​

Branchez-vous sous condition​

Le nœud condition vérifie la valeur reçue sur son port field et active soit son port true, soit son port false Seuls les nœuds connectés au port actif sont exécutés ; les autres sont ignorés.

Un flux de travail, deux branches : un résultat de laboratoire est acheminé vers un enregistrement à forte valeur ajoutée ou un enregistrement de routine, et la branche non empruntée est ignorée.

Téléchargez la définition JSON ou YAML complète, ainsi que des exemples d'entrées. Les fichiers téléchargés utilisent le format d'exportation du générateur (definition.nodes et definition.connections).

Le même schéma de branchement en YAML abrégé (edges est l'alias de connexion) :

nodes:
- id: result
type: input
config:
required_fields: [patient_id, test, value]
defaults: {patient_id: "test-patient-a", test: "potassium", value: 4.2}
- id: pick-value
type: jsonpath
config:
path: value
- id: above-threshold
type: condition
config:
field: value
condition_type: greater_than
compare_value: 5.5
pass_through: {record: context}
- id: high-value
type: transform
config:
transformation_type: map
mappings: {patient: input.record.patient_id, test: input.record.test, value: input.record.value}
- id: routine
type: transform
config:
transformation_type: map
mappings: {patient: input.record.patient_id, test: input.record.test, value: input.record.value}
- id: out
type: output
edges:
- {source_node: result, source_port: output, target_node: pick-value, target_port: data}
- {source_node: pick-value, source_port: value, target_node: above-threshold, target_port: field}
- {source_node: result, source_port: output, target_node: above-threshold, target_port: context}
- {source_node: above-threshold, source_port: "true", target_node: high-value, target_port: input}
- {source_node: above-threshold, source_port: "false", target_node: routine, target_port: input}
- {source_node: high-value, source_port: result, target_node: out, target_port: input}
- {source_node: routine, source_port: result, target_node: out, target_port: input}

Chaque arête utilise un port déclaré par le nœud, ce qui permet de dessiner l'ensemble du flux de travail dans l'éditeur. Deux arêtes partent du nœud d'entrée : l'une arrive sur le port pick-value (la condition reçoit donc le nombre brut sur le port field) et l'autre sur le port context de la condition (l'enregistrement complet est ainsi transmis sur la branche choisie). Connecter directement le port output du nœud d'entrée au field ne fonctionne pas : le port transmet l'enregistrement complet et la comparaison échoue avec le résultat values must be numeric for > comparison. Le paramètre field du nœud condition (value) indique le nombre testé ; la valeur reçue sur le port field est celle qui est comparée.

Résultat des deux exécutions :

valuePort actifhigh-valueroutineout reçoit
4.2falsesautécouru{patient: "test-patient-a", test: "potassium", value: 4.2}
6.1truecourusauté{patient: "test-patient-a", test: "potassium", value: 6.1}

Les deux branches alimentent un nœud out L'exécution se termine avec une branche ignorée ; une jointure après une branche est donc sans risque. Pour plus de deux résultats, utilisez les conditions router nœud (rules, default_route) ou en chaîne.

Filtrer et regrouper une liste​

Utilisez filter pour conserver les enregistrements correspondants, puis aggregator pour les compter ou les résumer.

nodes:
- id: labs
type: input
config:
defaults:
data:
- {patient_id: "pt-a", test: "potassium", value: 4.1}
- {patient_id: "pt-b", test: "potassium", value: 6.2}
- {patient_id: "pt-c", test: "potassium", value: 5.9}
- {patient_id: "pt-d", test: "potassium", value: 3.8}
- id: critical
type: filter
config:
logic: AND
conditions:
- {field: value, operator: greater_than, value: 5.5}
- id: count
type: aggregator
config: {aggregation_type: count}
edges:
- {source_node: labs, source_port: data, target_node: critical, target_port: data}
- {source_node: critical, source_port: filtered_data, target_node: count, target_port: data}

Le nœud filter renvoie filtered_data (les enregistrements correspondants) avec filtered_count. Exécuté sur les quatre enregistrements ci-dessus, il conserve pt-b et pt-c, et le aggregator renvoie {"count": 2}.

Connectez la liste, pas l'enveloppe.

Le port aggregator attend un tableau. Connecté à result, il reçoit l'objet wrapper et échoue avec le data must be an array Connectez le champ filtered_data à son port data.

Les opérateurs de filtrage comprennent equals, not_equals, greater_than, less_than, contains, starts_with, regex, in, not_in, exists, is_empty et is_null (et leurs formes abrégées gt, ==, >=). aggregation_type peut être count, sum, average, min, max, group ou distinct.

Combiner deux sources​

Deux nœuds indépendants s'exécutent en parallèle dans le même lot. Fusionnez-les avec un nœud merge :

  - id: combine
type: merge
config: {merge_type: object, sources: [demographics, vitals]}
edges:
- {source_node: demographics, source_port: output, target_node: combine, target_port: demographics}
- {source_node: vitals, source_port: output, target_node: combine, target_port: vitals}

Avec demographics = {patient_id: "pt-a", name: "Test Patient A"} et vitals = {heart_rate: 72, spo2: 97}, merge a renvoyé merged: {heart_rate: 72, name: "Test Patient A", patient_id: "pt-a", spo2: 97}, field_count: 4 et source_count: 2. merge_type est object, array ou concat.

Parcourir une liste​

Le nœud loop (loop_type : for_each, while ou until) émet une liste avec un index pour chaque élément :

{"count": 2, "results": [{"index": 0, "item": {"patient_id": "pt-a"}}, {"index": 1, "item": {"patient_id": "pt-b"}}]}
La boucle n'exécute pas une branche une fois par élément.

Le nœud génère la liste indexée une seule fois, et les nœuds suivants s'exécutent une seule fois. Il ne répète pas la branche aval pour chaque élément. Un graphe de flux de travail ne peut jamais contenir de cycle (le moteur le rejette à la compilation). Pour un traitement par enregistrement, utilisez batch (batch_size, parallelism, continue_on_error) ou effectuez le traitement dans un nœud acceptant une liste.

Gérer l'échec intentionnellement​

Par défaut, un nœud défaillant entraîne l'échec de l'exécution (fail_fast). Vous pouvez modifier ce comportement pour un nœud donné avec error_handling, et vous pouvez relancer les erreurs transitoires avec retry.

Voici ce que la stratégie error_handling fait au reste de l&#39;exécution : fail_fast arrête l&#39;exécution ; log_and_continue termine le nœud dégradé et le nœud suivant ne s&#39;exécute que s&#39;il accepte l&#39;état dégradé.

  - id: write
type: fhir-crud
config: {operation: transaction, fhir_url: "{{FHIR_URL}}"}
error_handling: {strategy: log_and_continue} # fail_fast (default), log_and_continue, fallback
retry: {max_retries: 3, initial_delay_ms: 500, backoff_factor: 2, jitter: true}
- id: report
type: output
accept_outcomes: [succeeded, degraded] # needed to run after a degraded node

Lors du test, write a échoué à l'exécution car l'élément fourni n'était pas un Bundle. Voici ce que le moteur a fait :

ParamètreRésultat
fail_fastwrite a échoué avec transaction input must be a Bundle, got resourceType=<nil> et l'exécution s'est terminée failed.
log_and_continue, nœud suivant sans accept_outcomeswrite terminé avec le résultat degraded et des sorties vides, et le nœud suivant a échoué : node after requires a successful outcome from bad (received degraded).
log_and_continue, nœud suivant avec accept_outcomes: [succeeded, degraded]Le nœud suivant s'est exécuté et l'exécution s'est terminée partial.

Utilisez log_and_continue uniquement lorsque le reste du flux de travail peut se poursuivre sans le résultat de cette étape, et laissez le nœud suivant gérer les données manquantes. Une exécution se terminant par partial n'est pas une réussite : surveillez-la.

Autres nœuds de contrôle : validator (rules, strict_mode ; avec strict_mode hors d'un enregistrement défaillant passe avec valid=false), error-handler (strategy : catch, fallback, transform, retry_info) et delay.

Avant de vous fier à un flux de travail​

  • Chaque champ obligatoire possède une valeur, et les identifiants exacts des nœuds proviennent de la palette.
  • Vous l'avez exécuté avec une entrée normale, une entrée limite et une entrée avec champ manquant.
  • Aucun nœud n'est ignoré sauf si vous vous y attendiez.
  • Les nombres sont des nombres, et aucune variable ne recèle de secret.
  • La gestion des échecs est délibérée : vous savez ce que signifie un résultat degraded ou partial pour l’étape suivante.
  • Tout système qui écrit dans un système clinique génère des propositions ou des ébauches, et non des dossiers définitifs, sauf si une personne les vérifie. Voir Agents et gouvernance.
  • Vous avez effectué vos tests uniquement avec des données synthétiques.

Quand ça ne fonctionne pas​

SymptômeCause probableRéparer
Un nœud indique qu'il a été ignoré.Son interface d'entrée se trouve sur un port condition qui n'était pas actif, ou le nom d'un port sur une interface est incorrect.Vérifiez le nom du port source sur le périphérique (true ou false pour une condition).
Un champ mappé est null.Le mappage ne comporte pas le préfixe du nom de port.Utilisez input.<field>.
values must be numeric for > comparisonUne valeur textuelle a fait l'objet d'une comparaison numérique.Indiquez un nombre.
data must be an arrayUn nœud de liste a reçu son objet enveloppe.Connectez le champ de liste (par exemple filtered_data).
compilation failed: node release xyz@ is unavailableL'identifiant du nœud ne figure pas dans le catalogue.Copiez l'identifiant depuis la palette.
compilation failed: ... circular dependency detectedLe graphique possède un cycle.Enlevez le bord qui forme une boucle.
node ... validation failed: <field> is requiredUn paramètre obligatoire est vide.Remplissez-le dans l'inspecteur.
requires a successful outcome from <node> (received degraded)Le nœud précédent s'est terminé degraded sous log_and_continue.Ajoutez accept_outcomes à ce nœud, ou cessez d'utiliser log_and_continue sur le nœud précédent.
Le résultat est partial.Au moins un nœud s'est terminé avec degraded.Ouvrez le fichier run dans Monitor et vérifiez lequel.

D'autres erreurs, avec le détail des erreurs liées au flux de données, se trouvent dans la section Ports, types et flux de données.

Et ensuite ?​

Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.