Aller au contenu principal

Créer un tuyau de connexion

Objectif : recevoir des messages d’un système externe, les acheminer vers une destination et vérifier leur bon fonctionnement. Vous créez le pipeline en Tiet · Connect → Network → Pipes, sans aucun flux de travail.

Utilisez un tube Connect pour un transport simple : écoute, transformation optionnelle, livraison. Si vous souhaitez définir le traitement de chaque message à l’aide de nœuds de workflow, utilisez plutôt la route de workflow : Recette : ADT vers FHIR.

Vous aurez besoin : de l’autorisation de consulter et de modifier les canaux Connect, d’un serveur Connect en mode autonome (par défaut), d’une destination et d’un moyen d’envoyer un message de test. Cette page utilise deux exemples :

  1. HL7 via MLLP en entrée, HTTP en sortie. Cas typique en milieu hospitalier.
  2. Kafka en entrée, fichier en sortie. Un deuxième type de source et de destination.

Pour plus d'informations sur les modes, la santé et les connecteurs, voir Tiet · Connect.

Exemple 1 : HL7 sur MLLP vers un point de terminaison HTTP​

Ouvrir le générateur​

  1. Dans le menu de navigation de gauche, choisissez Tiet · Connect → Network, puis ouvrez Pipes.
  2. Cliquez sur New pipe. Le constructeur s'ouvre avec six étapes sur la gauche : Basics, Source, Processing, Destinations, Routing, Review. Un indicateur d'achèvement affiche « n/5 sections prêtes ».

Tiet · Connect → Réseau → Tuyaux, avec le bouton Nouveau tuyau

Étape 1 : Notions de base​

ChampExempleNotes
Channel nameDemo ADT to webhookObligatoire. Unique au sein de votre organisation.
DescriptionSynthetic ADT messages to a test webhookFacultatif.
Tagshl7, demoSéparés par des virgules.
Enable on createsurActivé par défaut.

Étape 2 : Source​

Choisissez Type TCP (MLLP/HL7) (réseau de groupe). Les champs :

ChampExempleNotes
Bind Host0.0.0.0
Port2575Requis.
FramingMLLPChoisissez MLLP. Raw TCP correspond à un autre écouteur, non-HL7.
Delimiterlaisser videTCP brut uniquement.

Étape 3 : Traitement​

Laissez la liste vide. La page affiche « Aucun processeur pour l'instant — les messages sont transmis sans transformation ». Cet exemple transmet le texte HL7 tel qu'il arrive.

L'étape propose onze boutons sous Add a transformer or processor : Pipeline, Anonymizer, Filter, Tag Transformer, AI Inference, JavaScript, HL7 to FHIR, FHIR to HL7, XPath, JSONPath et Regex. Chaque bouton ajouté devient une carte numérotée sous Pipeline order, avec un bouton d'activation, un formulaire de configuration (ou une boîte JSON si le type n'a pas de format connu) et une liste On error (Stop on error, Skip on error, Fallback on error). Les processeurs s'exécutent de haut en bas. L' Pipeline vous invite à sélectionner un flux de travail déployé. Avant d'utiliser ces éléments, consultez le document « HL7 vers FHIR : ce qu'il faut savoir » : le générateur enregistre les cartes, mais le moteur n'en exécute que certaines.

Étape 4 : Destinations​

Cliquez sur la liste Type de Destination 1 et choisissez HTTP / HTTPS. Les champs :

ChampExempleNotes
URLhttps://webhook.example.org/hl7Obligatoire. Utilisez un récepteur de test que vous contrôlez.
MethodPOSTPOST, PUT, PATCH ou GET.
Content-Typetext/plainLa valeur par défaut est application/json. HL7 v2 n'est pas au format JSON, il faut donc la définir.
Timeout (ms)30000
Auth Typenonebasic, bearer ou api_key nécessitent les champs correspondants (Nom d'utilisateur et mot de passe, jeton d'authentification, en-tête de clé API et valeur de clé API).
Idempotency Key / Idempotency HeadervideOptionnel. Envoie un en-tête (par exemple Idempotency-Key) permettant au destinataire d'ignorer les doublons. Sans en-tête ni clé, Connect utilise le hachage de la charge utile.

Add destination ajoute des destinations supplémentaires. Chaque destination reçoit chaque message.

Étape 5 : Routage​

Delivery route a deux choix :

  • Direct (source → destination) : traité sur cette instance Connect. Choisissez-la pour l’exemple.
  • On mesh (rayon → hub → rayon) : choisissez un Source spoke et un Destination spoke. Sans rayons enregistrés, la page indique : « Aucun rayon n’est encore enregistré. Enregistrez un rayon dans la vue Mesh pour acheminer ce canal à travers le maillage. »
attention

L'API Connect ne conserve pas les choix de canaux secondaires envoyés via le formulaire. Le serveur ignore les valeurs source_spoke_id et destination_spoke_id des requêtes de création et de mise à jour, car seul le point de terminaison de la route principale (jeton du maillage) peut les définir. Par conséquent, la sélection des canaux secondaires dans l'éditeur peut ne pas modifier la route. Après l'enregistrement, vérifiez la route dans l'inspecteur de canaux ou la vue Mesh avant de vous y fier.

Processing settings:

ChampDéfautSignification
Max threads1Travailleurs parallèles pour le canal.
Queue buffer size1000Taille de la file d'attente du canal. Lorsqu'elle est pleine, le message est abandonné et marqué comme Erreur avec Queue full.
Preserve per-key orderdésactivéBêta. Conserve les messages ayant la même clé (HL7 PID-3, sujet FHIR) dans l'ordre d'arrivée entre les fils de discussion. L'activation de cette fonction affiche Ordering key source ; laissez ce champ vide pour que la clé soit déduite du message.
attention

Avec Max threads au-dessus de 1 et Preserve per-key order désactivé, deux messages destinés au même patient peuvent être envoyés dans le désordre. Pour le trafic ADT, conservez Max threads à 1, ou activez l'ordonnancement et effectuez un test.

Cette étape comprend également des boutons bascule (Store messages, Encrypt data, Export data, Remove content on complete), un groupe Advanced éléments (Message storage mode, Clear global channel map on redeploy et FHIR batching, voir ci-dessous) et quatre zones de script (Preprocessing script, Postprocessing script, Deploy script, Undeploy script). Laissez leurs valeurs par défaut pour cet exemple.

Étape 6 : Révision​

La liste affiche le canal, la source, le traitement (« Transmission automatique » si ces champs sont vides), les destinations et l'itinéraire, chacun comportant un bouton permettant de revenir en arrière. Si un élément est manquant, un message s'affiche : « Ajoutez un nom de canal pour continuer. », « Choisissez un connecteur source. » ou « Ajoutez au moins une destination. »

Cliquez sur Create channel. Le message affiché est « Canal créé ».

Déployez le tuyau​

Le nouveau tuyau apparaît dans la section « Tubes » avec l’étiquette d’état Ready : il existe mais n’est pas encore à l’écoute. Cliquez sur le tuyau, puis sur Resume dans le pied de page de l’inspecteur. L’étiquette passe à Deployed.

remarque

L'étape de vérification indique que le canal « sera ajouté et déployé sur le maillage ». En pratique, la Create channel ne fait que le créer. Déployez-le avec Resume.

Envoyer un message de test​

Utilisez l'interface de ligne de commande de simulation à partir de tietai-simulation-service. Elle n'envoie que des patients synthétiques.

sim-cli hl7 send --host <connect-host> --port 2575 --type ADT^A01 --count 1 --verbose

Options vérifiées dans app/cli/main.py : -H/--host (par défaut localhost), -p/--port, -t/--type (ADT^A01, ADT^A03, ADT^A04, ADT^A08, ORU^R01, ORM^O01), -n/--count, -r/--rate, -f/--file (votre propre fichier ; - est stdin), -v/--verbose, --timeout (secondes, par défaut 10) et --no-ack. La commande envoie le message via MLLP et vérifie l'accusé de réception : AA ou CA compte comme succès.

remarque

Le récepteur MLLP envoie son accusé de réception dès que le message est accepté dans la file d'attente du canal. Il n'attend pas la livraison à destination. Un accusé de réception de Connect ne prouve pas que la destination l'a reçu. Consultez les messages du canal, comme ci-dessous.

Vérifier le résultat​

  1. Cliquez sur le tuyau, puis Messages. Un tiroir s'ouvre avec les onglets In channel et Dead-letter, chacun avec un compteur.
  2. Sur In channel, les filtres d'état sont All, Sent, Buffered, Queued et Error. Le champ de recherche accepte un identifiant de message ou un nom de patient. La liste s'actualise toutes les 20 secondes.
  3. Sélectionnez votre message. Le volet de détails affiche le statut : Route, Errors (le cas échéant), Headers et Payload (onglets par représentation, par exemple : Brut, Transformé, Traité, Réponse).

Vous devriez voir : un message avec le statut Sent et le même texte HL7 arrivant à votre webhook.

StatutSignification
ReceivedStocké à l'arrivée.
SentToutes les destinations l'ont accepté.
BufferedLes destinataires l'ont accepté, mais au moins un ne l'a pas conservé. Il devient « Envoyé » lorsque le destinataire le confirme. Ce n'est pas la même chose que « Envoyé ».
QueuedTransmis au module de traitement par lots FHIR (voir la section « Traitement par lots FHIR » ci-dessous) et en attente de la réponse du serveur FHIR. Le statut devient « Envoyé » ou « Erreur ».
ErrorToutes les destinations ont échoué, la file d'attente était pleine ou le serveur FHIR a rejeté un lot.

Si une destination parmi plusieurs échoue, le message reste indiqué comme envoyé (ou mis en mémoire tampon) et la liste des erreurs affiche « Succès partiel :… ». Consultez cette liste lorsqu'il semble manquer des données pour une destination. La liste Recent messages de l'inspecteur de flux affiche les six dernières erreurs.

Gérer les défaillances​

Une livraison infructueuse laisse le message avec le statut Error. Pour les voir tous, ouvrez l'onglet Dead-letter du tiroir (ce tuyau) ou Tiet · Connect → Network → DLQ (tous les tuyaux).

  • Mode autonome : la vue des messages non distribués est en lecture seule. Le message indique : « Lecture seule : cette instance de Connect fonctionne en mode autonome et ne peut ni relire ni supprimer les messages non distribués. » Corrigez le problème, puis renvoyez le message depuis la source. Dans l’onglet In channel, Discard (puis Delete) supprime l’enregistrement d’un message.
  • Mode Hub : sélectionnez une lettre non distribuée et choisissez Replay ou Discard avec une raison. Replay page relance toutes les lettres non distribuées de la page. Dans la console DLQ, vous pouvez également en sélectionner plusieurs, et Expire old supprime les enregistrements anciens résolus ou rejetés.

Défaillances courantes :

Ce que vous voyezCause et solution
Le tuyau reste ReadyIl a été créé mais pas déployé. Cliquez sur Resume.
L'expéditeur ne peut pas se connecter.Le canal est Ready ou en pause, ou le port 2575 est inaccessible. Reprenez le canal et vérifiez le chemin réseau.
Message Error, le texte commence à HTTP request failed with statusLa destination a renvoyé un code d'état autre que 2xx. Le texte inclut le corps de la réponse. Veuillez corriger l'URL, les identifiants ou le type de contenu.
Message Error, texte HTTP request failed:La destination est inaccessible (DNS, TLS, délai d'attente dépassé).
Message Error, le texte commence par FHIR server rejected the transaction ou BATCH_TIMEOUTTraitement par lots FHIR : le serveur a refusé le lot ou n’a pas répondu. Consultez les codes d’erreur et vérifiez la propriété du jeton d’authentification.
Message Error, texte Queue fullVoir Queue buffer size et Max threads.
Message Error, texte All destinations failed: ...Le préfixe de l'erreur. Les noms qui suivent indiquent la destination concernée.
Étiquette de tuyau Errors recorded ou High error shareLes compteurs sont cumulatifs depuis leur création. Ouvert Messages → Error.

Exemple 2 : Kafka vers un fichier​

Ceci indique une deuxième source et destination et ne nécessite aucun récepteur HTTP.

  1. Notions de base : nom Demo Kafka to file.
  2. Source : Type Apache Kafka. Champs : Brokers (obligatoire, séparés par des virgules, par exemple kafka.example.org:9092), Topic (obligatoire, sim.inbound), Consumer Group (tietai-connect).
  3. Traitement : vide.
  4. Destinations : Type File System. Champs : Directory (obligatoire, /data/outgoing), Filename Pattern (msg_${timestamp}.txt), Append (désactivé), Create Dirs (activé), File Mode (0644). Le répertoire se trouve sur le serveur Connect.
  5. Routage : Direct. Review → Create channel, puis Resume.
  6. Envoyer un enregistrement de test :
sim-cli kafka send --bootstrap kafka.example.org:9092 --topic sim.inbound --format hl7v2 --count 3

--format vaut hl7v2, fhir, raw ou auto ; --key définit la clé d’enregistrement (par défaut : le numéro MRN du patient). Ouvrir Messages → In channel : trois messages et trois fichiers dans /data/outgoing.

Transition de HL7 à FHIR : ce que vous devez savoir​

Le générateur comporte une entrée HL7 to FHIR dans l'étape de traitement et un type de destination FHIR REST Voici ce que fait le code de connexion, vérifié aux channel_engine.go, internal/transformers/transformer.go, internal/connectors/http.go et fhir_batcher.go.

1. Entrée du processeur. Le générateur permet d'ajouter une carte HL7 to FHIR et l'enregistre dans la liste des processeurs du canal, mais le moteur ne l'exécute pas. La chaîne de processeurs du moteur (initProcessorChain, processors.NewDefaultRegistry) ne reconnaît que quatre processeurs DICOM : filter, anonymizer, tag-transformer et ai-inference, et les applique uniquement au contenu DICOM JSON. Tout autre type de processeur (y compris hl7_to_fhir, fhir_to_hl7, javascript, xpath, jsonpath et regex) empêche la création de la chaîne. Connect consigne alors « Échec de la création de la chaîne de processeurs » sur le serveur et ignore la chaîne entière, y compris les processeurs DICOM de la même liste. Le générateur enregistre également tag_transformer et ai_inference avec des tirets bas, que le registre ne reconnaît pas non plus. Seul Pipeline (hydra_pipeline) s'exécute sur son propre chemin, et uniquement si le serveur Connect a HYDRA_API_URL défini et CONNECT_AGENTIC_PROCESSORS_ENABLED non faux. Le moteur effectue la conversion HL7 vers FHIR uniquement lorsque la propriété transform_to_fhir du canal est définie sur true (paramétrée par le canal HL7 initialisé par Connect). Le générateur ne dispose d'aucun champ pour cette propriété. Si une conversion est nécessaire sur un canal, définissez la propriété via l'API du canal ou utilisez le flux de travail décrit dans la recette : ADT vers FHIR. Pour les résultats du laboratoire ORU^R01, la propriété transformer_type définie sur HL7_ORU_TO_FHIR (avec transformer_options) sélectionne un mappage prenant en compte l'ordre, qui génère un bundle de transactions et rejette le message au lieu de transmettre le HL7 brut. Effectuez un test avec un message synthétique et consultez l'onglet Payload avant d'utiliser une conversion.

2. Type de lot. Avec la conversion par défaut de HL7_TO_FHIR, le lot produit contient type: "collection" entrée ayant fullUrl mais aucune request. Il ne s'agit pas d'un lot de transactions.

3. Destination REST FHIR. FHIR REST correspond au connecteur HTTP (fhir_rest correspond à HTTP). Il envoie le corps du message, sans modification, à FHIR Server URL avec la Method choisie (POST ou PUT), et avec Content-Type: application/fhir+json sauf si vous la modifiez. Il ne convertit pas un Bundle de collection en transaction. Un serveur FHIR qui attend une transaction ou un lot à son URL de base rejettera un Bundle de collection, et le message affichera Error avec HTTP request failed with status ... et le texte du serveur.

4. Traitement par lots FHIR. À l'étape 5, activez FHIR batching et définissez FHIR server URL (le traitement par lots est inactif sans cette valeur). Champs : Batch size, Batch timeout (s), Max concurrent batches, FHIR server URL. Lorsque le type de données du moteur est FHIR, les ressources sont collectées et publiées sous forme de bundle de transactions à l'URL indiquée. Une ressource seule ou une entrée de bundle de collection devient une entrée POST pour son type de ressource ; un bundle de transactions dont les entrées ont déjà une valeur request est mis en file d'attente, entrée par entrée, sans modification. Si le champ « Taille » est laissé vide, les valeurs par défaut du moteur sont utilisées : 25 ressources, 5 secondes, 20 lots simultanés. Le traitement par lots ignore les connecteurs de destination.

  • Le message affiche Queued jusqu'à ce que le serveur FHIR réponde. Une réponse 2xx le fait passer Sent. Un rejet ou un échec de transport le fait passer Error, avec un texte tel que « Le serveur FHIR a rejeté la transaction (HTTP 400) :… ». Si aucune réponse n'arrive à temps, Connect le marque à Error avec BATCH_TIMEOUT (délai d'expiration du lot plus environ une minute) et le message peut être retraité ;
  • L'authentification n'est pas un champ de construction. Le traitement par lots envoie Authorization: Bearer ... uniquement lorsque la propriété de canal fhir_bearer_token_env (nom d'une variable d'environnement sur le serveur Connect) ou fhir_bearer_token est définie. En l'absence de cette propriété, Connect consigne un avertissement et envoie la transaction sans en-tête d'authentification. Il envoie systématiquement X-Organization-ID, Content-Type et Accept: application/fhir+json.

Définissez la propriété du jeton via l'API du canal avant de diriger le traitement par lots vers un serveur FHIR qui a besoin d'un jeton.

Si vous avez besoin aujourd'hui d'une route HL7 vers FHIR vérifiée, créez-la sous forme de flux de travail avec les nœuds hl7-to-fhir et fhir-crud Cette route publie un bundle de transactions. Voir la recette : ADT vers FHIR.

Changer ou retirer un tuyau​

  • Dans l'inspecteur de tuyauterie, Edit ouvre un panneau latéral affichant le nom, le tracé, les destinations et les transformations. Full editor ouvre les mêmes six étapes avec les valeurs enregistrées ; le bouton Enregistrer affiche Save changes.
  • Pause déploiements. Rien n'écoute tant que vous n'en avez Resume.

Que faire ensuite ?​

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