Aller au contenu principal

Recette : Recevoir des messages HL7 ADT dans FHIR

Objectif : un système hospitalier envoie des messages d'admission (HL7 v2 ADT) à Tietai. Un flux de travail reçoit chacun d'eux, le convertit en FHIR Patient et Encounter, et les écrit sur votre serveur FHIR.

Vous aurez besoin de : environ 30 minutes, l'autorisation de créer des flux de travail, une URL de serveur FHIR R4 et un jeton d'accès, et une personne du côté de l'hôpital qui peut envoyer HL7 à un hôte et un port.

Un système hospitalier envoie un message HL7 au serveur MLLP du moteur de workflow sur le port 2575. Ce serveur recherche les workflows enregistrés à l'aide d'un nœud d'écoute HL7, exécute le workflow et renvoie un accusé de réception. Le workflow convertit ensuite le message en un bundle de transactions et l'écrit avec fhir-crud.

Ce que vous obtenez, et ce que vous n'obtenez pas​

Ce test a été exécuté sur le moteur réel avec un message ADT^A01 synthétique :

RésultatDétail
PatientIdentifiant (le numéro MRN du PID-3), nom, date de naissance, sexe
EncounterClasse IMP (hospitalisé), statut in-progress, localisation de PV1 à 3, lié au patient
Not convertedPersonne à contacter en cas d'urgence (NK1), numéro de visite, détails de l'événement (EVN), allergies et diagnostics. Le rapport de course indique NK1 sur unmapped_segments.

Connaissez ces limites avant de vous y fier :

  • Chaque message crée de nouvelles ressources. Chaque entrée est égale à POST. Il n'y a pas de correspondance avec un patient existant, aucune mise à jour, et le statut de la rencontre est toujours in-progress.
  • Ainsi, une sortie (A03) ne ferme pas la rencontre, une mise à jour (A08) crée un deuxième patient et une deuxième rencontre, et le renvoi du même message le duplique.
  • Commencez par les admissions uniquement (filter_event = A01), et ajoutez votre propre étape de correspondance ou de mise à jour avant d'accepter d'autres événements.

Avant de commencer​

  1. Autorisations. Vous pouvez ouvrir Tiet · Studio → Workflows.
  2. Serveur FHIR. Vous disposez de son URL de base (par exemple https://fhir.example-hospital.org/r4) et d'un jeton d'authentification.
  3. Réseau. Le moteur de workflow reçoit les données HL7 sur un port serveur unique, le port 2575 par défaut (défini par votre administrateur avec la MLLP_PORT). L'interface de l'hôpital envoie les données au <your-hydra-host>:2575. La valeur listen_port du paramètre du récepteur doit correspondre à ce port serveur, car c'est ainsi que le workflow est associé. Sa valeur listen_host n'est pas utilisée : l'adresse de liaison est également globale au serveur.
  4. Nom de l'expéditeur. Demandez l'application et le système d'envoi (MSH-3 et MSH-4) ; vous pouvez filtrer les résultats en fonction de ces critères.
Chaque flux de travail d'écoute enregistré reçoit chaque message sur ce port

Le serveur transmet chaque message entrant à chaque flux de travail enregistré contenant un nœud hl7-listener sur ce port. La recherche ne tient pas compte du déploiement, de l'activité ni de l'organisation du flux de travail. Ne laissez pas de flux de travail de test enregistré pendant que du trafic est en production et demandez à votre administrateur de confirmer qu'aucun autre flux de travail enregistré n'écoute sur votre port.

Élaborer le flux de travail​

1. Créez-le​

  1. Ouvrez Tiet · Studio → Workflows et choisissez New Workflow.
  2. Dans l'onglet Palette, recherchez chaque nœud ci-dessous et faites-le glisser sur le canevas. Sélectionnez un nœud pour le modifier dans l' Inspector (Display name sous Identity, les paramètres sous Node Settings ; les paramètres de l'écouteur sont répartis sur les onglets Connection, Filtering, Security, Ack et Advanced).

2. Configurer les quatre nœuds​

hl7-listener (HL7 Listener) reçoit le message et envoie l'accusé de réception.

ParamètreValeurNotes
listen_port2575Doit correspondre au port MLLP du serveur
filter_message_typeADTIgnorez tout ce qui n'est pas ADT.
filter_eventA01Entrée libre uniquement. Laissez ce champ vide pour accepter tous les événements (voir les limites ci-dessus).
filter_sending_applicationpar exemple EPICFacultatif
filter_sending_facilitypar exemple GENHOSPFacultatif
ack_modeautoLe récepteur répond après l'exécution : AA (accepté), AE (échec de l'exécution) ou AR (rejeté avant traitement). manual permet à l'exécution de définir le code ; none n'envoie aucun accusé de réception.
nack_on_filterfalseVoir le tableau des défaillances ci-dessous
allowed_ipspar exemple 10.0.0.0/24Optionnel : accepter uniquement les connexions provenant du réseau hospitalier

hl7-to-fhir (HL7 vers FHIR) ne nécessite aucun paramétrage. Définissez default_timezone (par exemple Europe/Madrid) si les horodatages des messages ne contiennent pas de fuseau horaire. Il détecte le type à partir de MSH-9 et renvoie un objet result qui contient le Bundle dans fhir_bundle.

transform, nommé Pick the Bundle, extrait le Bundle de cet objet afin que le nœud d'écriture reçoive un Bundle et non son wrapper.

ParamètreValeur
Transformation Type (transformation_type)extract
Mappings (mappings)Choisissez Add field trois fois ; sur chaque ligne, saisissez Target et Source (dot path ok) : resourceType sur input.fhir_bundle.resourceType, type sur input.fhir_bundle.type, entry sur input.fhir_bundle.entry

fhir-crud (FHIR CRUD) écrit le Bundle.

ParamètreValeur
fhir_urlhttps://fhir.example-hospital.org/r4 (ou {{FHIR_URL}} avec une variable non secrète)
operationtransaction
auth_tokenCollez le jeton dans ce champ.
Où va le jeton

Le champ auth_token est secret : collez-y le jeton. Ne le stockez pas comme variable secrète et n’écrivez pas {{FHIR_TOKEN}} : une variable secrète n’est pas substituée, le serveur recevrait donc le texte littéral Bearer {{FHIR_TOKEN}}. Une variable non secrète convient parfaitement pour l’URL.

3. Connectez les ports​

DepuisPortÀPort
Écouteur HL7raw_messageHL7 vers FHIRhl7_message
HL7 vers FHIRresultChoisissez le packinput
Choisissez le packresultFHIR CRUDbundle

raw_message est du texte et hl7_message attend du texte ; ils sont donc connectés. Si vous connectez result directement à bundle, le nœud d'écriture reçoit l'objet wrapper et génère une erreur (code transaction input must be a Bundle, got resourceType=<nil>. C'est pourquoi l'étape d'extraction est nécessaire.

4. Valider et enregistrer​

Sélectionnez Validate dans la barre d'outils, puis Save (une version vous sera demandée ; acceptez la suggestion). Le flux de travail démarre la réception des messages dès l'enregistrement. Le déploiement (menu violet à droite de la barre d'outils, permettant de déployer la version enregistrée dans un autre environnement) n'est pas nécessaire à la réception des messages et n'impose aucune limitation quant aux types de messages reçus.

Testez-le avec un message synthétique​

Utilisez uniquement des données synthétiques. Ce message est un aveu inventé :

MSH|^~\&|EPIC|GENHOSP|TIETAI|HIP|20260915083000||ADT^A01^ADT_A01|SMP-A01-0001|P|2.5
EVN|A01|20260915083000|||USR100^Nurse^Maria
PID|1||MRN100001^^^GENHOSP^MR||Rivera^Elena^M||19750312|F|||742 Evergreen Terrace^^Springfield^IL^62704^USA||(217)555-0142||en|M
NK1|1|Rivera^Carlos|SPO^Spouse^HL70063||(217)555-0143
PV1|1|I|MED^301^A^GENHOSP|E|||2001^Smith^Anna^^^Dr|||MED||||7|||2001^Smith^Anna^^^Dr||V2026091501^^^GENHOSP^VN

HL7 sépare les segments par un retour chariot, et non par un saut de ligne. L'outil de simulation du dépôt l'envoie correctement et attend l'accusé de réception.

# from the tietai-simulation-service folder
sim-cli hl7 send -H <your-hydra-host> -p 2575 --file samples/hl7v2/adt_a01_admit.hl7 -v

Un accusé de réception de valeur AA signifie que le message a été accepté pour traitement.

Vérifier le résultat​

  1. L'exécution. Ouvrez Tiet · Studio → Workflows → Monitor. L'exécution de votre flux de travail devrait indiquer que les quatre nœuds ont réussi.
  2. Les données. Ouvrez FHIR Server → Patients et recherchez identifier=MRN100001 (une recherche contenant = est envoyée au serveur en tant que paramètre de recherche FHIR). Vous devriez trouver la patiente Rivera, Elena, de sexe féminin, née le 12 mars 1975, avec une consultation de classe IMP à l'emplacement MED 301 A GENHOSP. Le conjoint n'y figure pas, car NK1 n'est pas converti.

Quand quelque chose tourne mal​

SymptômeCauseCe qu'il faut faire
L'expéditeur ne peut pas se connecterAucun service n'écoute sur le port du serveur, ou un pare-feu le bloque.Demandez à votre administrateur de confirmer MLLP_PORT le port est ouvert depuis le réseau de l'hôpital.
L'expéditeur reçoit ARAucun flux de travail enregistré ne correspond à hl7-listener sur ce port (réponse par défaut du serveur lorsqu'aucun flux n'est à l'écoute) ; ou l'en-tête est illisible (MSH-9, MSH-10 ou MSH-12 manquants) ; ou la version n'est pas HL7 v2.x ; ou ce flux de travail a refusé le message (réponse allowed_ips ou max_message_size) ; ou tous les écouteurs l'ont filtré et l'un d'eux a défini nack_on_filterEnregistrez le flux de travail et vérifiez que listen_port correspond au port du serveur, puis vérifiez le segment MSH et l'adresse IP de l'expéditeur.
L'expéditeur reçoit AA mais rien ne se passe.Chaque récepteur a filtré le message. Par défaut, un message filtré est acquitté (AA) et ignoré.Vérifiez filter_message_type, filter_event, ainsi que les noms de l'expéditeur et de l'établissement. Configurez nack_on_filter à true pour répondre AR, afin que l'expéditeur voie le problème.
L'exécution échoue au niveau du dernier nœud.L'écriture FHIR a échouéOuvrir la piste en Monitor signifie que l'URL est vide ; une requête rejetée signifie généralement que le jeton ou l'URL est incorrect fhir_url is required
transaction input must be a Bundle, got resourceType=<nil>Le nœud d'écriture a reçu l'objet wrapper, et non le bundle.Vérifiez l'étape Pick the Bundle et ses correspondances.
INVALID_MSH_SEGMENT ou MISSING_HL7_MESSAGELe nœud d'écoute n'a reçu aucun message, ou le segment MSH est manquant ou comporte moins de 10 champs.Vérifiez le segment MSH du message
L'expéditeur obtient AR pour un message volumineuxLe message se trouve au-dessus du max_message_size du flux de travailLa limite maximale par défaut est de 1 048 576 octets (1 Mio) ; 0 supprime la limite par flux de travail. Le serveur possède également sa propre limite.

Adaptez-le​

  • Résultats (ORU) ou commandes (ORM) : hl7-to-fhir correspond également à ORU pour Patient plus Observation et Rapport de diagnostic, et à ORM pour Patient plus Demande de service. Modifiez le filtre et conservez le reste.
  • Réagissez à ce qui arrive : ajoutez un nœud condition après la conversion (voir Créer n’importe quel flux de travail), par exemple pour acheminer les admissions vers un service particulier.
  • Plusieurs hôpitaux ou sites : placez un écouteur sur chaque site avec Run on mesh.
  • Utilisez plutôt un canal Connect : créez un canal Connect qui reçoit les données HL7. Consultez la documentation relative à la conversion FHIR avant d’opter pour cette solution.

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