Receta: Recibir mensajes HL7 ADT en FHIR
Objetivo: un sistema hospitalario envía mensajes de admisión (HL7 v2 ADT) a Tietai. Un flujo de trabajo recibe cada uno, lo convierte en un FHIR Patient y Encounter, y los escribe en su servidor FHIR.
Necesitas: unos 30 minutos, permiso para crear flujos de trabajo, una URL de servidor FHIR R4 y un token de acceso, y alguien del hospital que pueda enviar HL7 a un host y puerto.
Lo que obtienes y lo que no.
Esto se ejecutó en el motor real con un mensaje sintético ADT^A01:
| Resultado | Detalle |
|---|---|
| Patient | Identificador (el MRN de PID-3), nombre, fecha de nacimiento, género |
| Encounter | Clase IMP (paciente hospitalizado), estado in-progress, ubicación de PV1-3, vinculado al paciente. |
| Not converted | El pariente más cercano (NK1), el número de visita, los detalles del evento (EVN), las alergias y los diagnósticos. Los informes de la carrera NK1 en unmapped_segments. |
Conoce estos límites antes de confiar en ello:
- Cada mensaje crea nuevos recursos. Cada entrada es un
POST. No hay coincidencia con un paciente existente, no hay actualización y el estado del encuentro siempre esin-progress. - Por lo tanto, un alta (A03) no cierra el encuentro, una actualización (A08) crea un segundo paciente y encuentro, y reenviar el mismo mensaje lo duplica.
- Comience solo con las admisiones (
filter_event=A01) y agregue su propio paso de coincidencia o actualización antes de aceptar otros eventos.
Antes de empezar
- Permisos. Puedes abrir Tiet · Studio → Workflows.
- Servidor FHIR. Tienes su URL base (por ejemplo,
https://fhir.example-hospital.org/r4) y un token de portador. - Red. El motor de flujo de trabajo recibe HL7 en un puerto del servidor,
2575por defecto (configurado por el administrador conMLLP_PORT). La interfaz del hospital envía a<your-hydra-host>:2575. La configuraciónlisten_portdel receptor debe ser igual a ese puerto del servidor, ya que así se realiza la coincidencia del flujo de trabajo. Su configuraciónlisten_hostno se utiliza: la dirección de enlace también es del servidor. - Los nombres de los remitentes. Solicite la aplicación y el centro de envío (MSH-3 y MSH-4); puede filtrar por ellos.
El servidor reenvía cada mensaje entrante a cada flujo de trabajo guardado que contenga un nodo hl7-listener en ese puerto. La búsqueda no tiene en cuenta si el flujo de trabajo está implementado, activo o a qué organización pertenece. No deje un flujo de trabajo de prueba guardado mientras haya tráfico real y pida a su administrador que confirme que ningún otro flujo de trabajo guardado está escuchando en su puerto.
Construir el flujo de trabajo
1. Créalo
- Abre Tiet · Studio → Workflows y elige New Workflow.
- En la pestaña Palette, busque cada nodo a continuación y arrástrelo al lienzo. Seleccione un nodo para editarlo en la Inspector (Display name debajo de Identity, la configuración debajo de Node Settings; la configuración del oyente está dividida en las pestañas Connection, Filtering, Security, Ack y Advanced).
2. Configurar los cuatro nodos
hl7-listener (Escucha HL7) recibe el mensaje y envía la confirmación.
| Configuración | Valor | Notas |
|---|---|---|
listen_port | 2575 | Debe ser igual al puerto MLLP del servidor. |
filter_message_type | ADT | Ignora todo lo que no sea ADT. |
filter_event | A01 | Solo se admiten personas. Déjelo en blanco para aceptar todos los eventos (y consulte los límites anteriores). |
filter_sending_application | p. ej EPIC | Opcional |
filter_sending_facility | p. ej GENHOSP | Opcional |
ack_mode | auto | El receptor responde después de la ejecución: AA (aceptado), AE (la ejecución falló) o AR (rechazado antes del procesamiento). manual permite que la ejecución establezca el código; none no envía ninguna confirmación. |
nack_on_filter | false | Consulte la tabla de fallos a continuación. |
allowed_ips | p. ej 10.0.0.0/24 | Opcional: aceptar conexiones solo desde la red del hospital. |
hl7-to-fhir (HL7 a FHIR) no necesita configuración. Establezca default_timezone (por ejemplo, Europe/Madrid) si las marcas de tiempo del mensaje no contienen zona horaria. Detecta el tipo de MSH-9 y devuelve un objeto result que contiene el Bundle en fhir_bundle.
transform, llamado Pick the Bundle, toma el Bundle de ese objeto para que el nodo de escritura reciba un Bundle y no su contenedor.
| Configuración | Valor |
|---|---|
Transformation Type (transformation_type) | extract |
Mappings (mappings) | Elige Add field tres veces; en cada fila escribe el Target y el Source (dot path ok): resourceType de input.fhir_bundle.resourceType, type de input.fhir_bundle.type, entry de input.fhir_bundle.entry |
fhir-crud (FHIR CRUD) escribe el paquete.
| Configuración | Valor |
|---|---|
fhir_url | https://fhir.example-hospital.org/r4 (o {{FHIR_URL}} con una variable no secreta) |
operation | transaction |
auth_token | Pegue el token en este campo. |
auth_token es un campo secreto: pega el token en él. No lo almacenes como una variable marcada como secreta y escribas {{FHIR_TOKEN}}: una variable secreta no se sustituye, por lo que el servidor recibiría el texto literal Bearer {{FHIR_TOKEN}}. Una variable no secreta es válida para la URL.
3. Conecte los puertos
| De | Puerto | A | Puerto |
|---|---|---|---|
| Oyente HL7 | raw_message | HL7 a FHIR | hl7_message |
| HL7 a FHIR | result | Elige el paquete | input |
| Elige el paquete | result | FHIR CRUD | bundle |
raw_message es texto y hl7_message espera texto, por lo que se conectan. Si conectas result directamente a bundle, el nodo de escritura recibe el objeto contenedor y falla con transaction input must be a Bundle, got resourceType=<nil>. Por eso existe el paso de extracción.
4. Validar y guardar
Seleccione Validate en la barra de herramientas y luego Save (le pedirá una versión; acepte la sugerencia). El flujo de trabajo comienza a recibir mensajes en cuanto se guarda. No es necesario usar la opción Implementar (el menú morado a la derecha de la barra de herramientas, que implementa la versión guardada en otro entorno) para que reciba mensajes, y esta opción no limita los mensajes que recibe.
Pruébalo con un mensaje sintético.
Utilice únicamente datos sintéticos. Este mensaje es una confesión inventada.
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 separa los segmentos con un retorno de carro, no con un salto de línea. La herramienta de simulación del repositorio lo envía correctamente y espera la confirmación:
# from the tietai-simulation-service folder
sim-cli hl7 send -H <your-hydra-host> -p 2575 --file samples/hl7v2/adt_a01_admit.hl7 -v
Una confirmación de AA significa que el mensaje fue aceptado para su procesamiento.
Comprueba el resultado
- La ejecución. Abrir Tiet · Studio → Workflows → Monitor. La ejecución de su flujo de trabajo debería mostrar que los cuatro nodos se ejecutaron correctamente.
- Los datos. Abra FHIR Server → Patients y busque
identifier=MRN100001(una búsqueda que contenga=se envía al servidor como parámetro de búsqueda FHIR). Debería encontrar a la paciente Rivera, Elena, mujer, nacida el 12/03/1975, con un encuentro de claseIMPen la ubicaciónMED 301 A GENHOSP. El cónyuge no está allí, porque NK1 no se ha convertido.
Cuando algo sale mal
| Síntoma | Causa | ¿Qué hacer? |
|---|---|---|
| El remitente no puede conectarse | Nada está escuchando en el puerto del servidor, o un cortafuegos lo bloquea. | Pídele a tu administrador que confirme MLLP_PORT el puerto está abierto desde la red del hospital. |
| El remitente recibe AR | Ningún flujo de trabajo guardado tiene un hl7-listener en ese puerto (la respuesta predeterminada del servidor cuando ninguno escucha); o el encabezado es ilegible (faltan MSH-9, MSH-10 o MSH-12) o la versión no es HL7 v2.x; o allowed_ips o max_message_size de este flujo de trabajo rechazó el mensaje; o todos los oyentes lo filtraron y uno establece nack_on_filter | Guarda el flujo de trabajo y comprueba que listen_port sea igual al puerto del servidor; luego, comprueba el segmento MSH y la dirección IP del remitente. |
| El remitente recibe AA pero no sucede nada. | Todos los oyentes filtraron el mensaje. Por defecto, un mensaje filtrado se reconoce como AA y se ignora. | Verifique filter_message_type, filter_event y los nombres del remitente y de la instalación. Configure nack_on_filter a true para responder AR en su lugar, para que el remitente vea el problema. |
| La ejecución falla en el último nodo. | La escritura en FHIR falló. | Abrir la ejecución en Monitor significa que la URL está vacía; una solicitud rechazada generalmente significa que el token o la URL son incorrectos fhir_url is required |
transaction input must be a Bundle, got resourceType=<nil> | El nodo de escritura recibió el objeto contenedor, no el Bundle. | Verifique el paso Pick the Bundle y sus asignaciones. |
INVALID_MSH_SEGMENT o MISSING_HL7_MESSAGE | El nodo receptor no recibió ningún mensaje, o el segmento MSH falta o tiene menos de 10 campos. | Compruebe el segmento MSH del mensaje. |
| El remitente recibe AR para un mensaje grande. | El mensaje está sobre el max_message_size del flujo de trabajo | El máximo predeterminado es 1048576 bytes (1 MiB); 0 elimina el límite por flujo de trabajo. El servidor también tiene su propio límite. |
Adáptalo
- Resultados (ORU) u órdenes (ORM):
hl7-to-fhirtambién asigna ORU a Paciente más Observación e Informe de diagnóstico, y ORM a Paciente más Solicitud de servicio. Modifique el filtro y conserve el resto. - Reacciona a lo que llega: agrega un nodo
conditiondespués de la conversión (consulta Crear cualquier flujo de trabajo), por ejemplo, para dirigir los ingresos a una sala en particular. - Varios hospitales o sitios: coloque un oyente en cada sitio con Run on mesh.
- En su lugar, como una tubería Connect: Cree una tubería Connect que reciba HL7 con una tubería. Lea sus notas sobre la conversión FHIR antes de elegir esa opción.
¿Algo no está claro? Envíe sus comentarios sobre la documentación por correo electrónico..