Saltar al contenido principal

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.

Un sistema hospitalario envía un mensaje HL7 al servidor MLLP del motor de flujo de trabajo en el puerto 2575. Este servidor localiza los flujos de trabajo guardados mediante un nodo hl7-listener, ejecuta el flujo de trabajo y devuelve una confirmación. El flujo de trabajo convierte el mensaje en un paquete de transacciones y lo escribe con fhir-crud.

Lo que obtienes y lo que no.​

Esto se ejecutó en el motor real con un mensaje sintético ADT^A01:

ResultadoDetalle
PatientIdentificador (el MRN de PID-3), nombre, fecha de nacimiento, género
EncounterClase IMP (paciente hospitalizado), estado in-progress, ubicación de PV1-3, vinculado al paciente.
Not convertedEl 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 es in-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​

  1. Permisos. Puedes abrir Tiet · Studio → Workflows.
  2. Servidor FHIR. Tienes su URL base (por ejemplo, https://fhir.example-hospital.org/r4) y un token de portador.
  3. Red. El motor de flujo de trabajo recibe HL7 en un puerto del servidor, 2575 por defecto (configurado por el administrador con MLLP_PORT). La interfaz del hospital envía a <your-hydra-host>:2575. La configuración listen_port del receptor debe ser igual a ese puerto del servidor, ya que así se realiza la coincidencia del flujo de trabajo. Su configuración listen_host no se utiliza: la dirección de enlace también es del servidor.
  4. Los nombres de los remitentes. Solicite la aplicación y el centro de envío (MSH-3 y MSH-4); puede filtrar por ellos.
Cada flujo de trabajo de escucha guardado recibe todos los mensajes en ese puerto.

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​

  1. Abre Tiet · Studio → Workflows y elige New Workflow.
  2. 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ónValorNotas
listen_port2575Debe ser igual al puerto MLLP del servidor.
filter_message_typeADTIgnora todo lo que no sea ADT.
filter_eventA01Solo se admiten personas. Déjelo en blanco para aceptar todos los eventos (y consulte los límites anteriores).
filter_sending_applicationp. ej EPICOpcional
filter_sending_facilityp. ej GENHOSPOpcional
ack_modeautoEl 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_filterfalseConsulte la tabla de fallos a continuación.
allowed_ipsp. ej 10.0.0.0/24Opcional: 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ónValor
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ónValor
fhir_urlhttps://fhir.example-hospital.org/r4 (o {{FHIR_URL}} con una variable no secreta)
operationtransaction
auth_tokenPegue el token en este campo.
Adónde va la ficha

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​

DePuertoAPuerto
Oyente HL7raw_messageHL7 a FHIRhl7_message
HL7 a FHIRresultElige el paqueteinput
Elige el paqueteresultFHIR CRUDbundle

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​

  1. 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.
  2. 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 clase IMP en la ubicación MED 301 A GENHOSP. El cónyuge no está allí, porque NK1 no se ha convertido.

Cuando algo sale mal​

SíntomaCausa¿Qué hacer?
El remitente no puede conectarseNada 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 ARNingú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_filterGuarda 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_MESSAGEEl 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 trabajoEl 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-fhir tambié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 condition despué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..