Crear una tubería de conexión
Objetivo: recibir mensajes de un sistema externo, entregarlos a un destino y demostrar que funcionó. La conexión se construye en Tiet · Connect → Network → Pipes, sin necesidad de flujo de trabajo.
Utilice una tubería Connect cuando desee un transporte simple: escuchar, transformar opcionalmente, entregar. Si desea decidir qué sucede con cada mensaje con nodos de flujo de trabajo, utilice la ruta de flujo de trabajo en su lugar: Receta: ADT a FHIR.
Necesitarás: permiso para ver y modificar los canales de Connect, un servidor Connect en modo independiente (el predeterminado), un destino al que enviar los mensajes y una forma de enviar un mensaje de prueba. Esta página utiliza dos ejemplos:
- HL7 sobre MLLP de entrada, HTTP de salida. El caso típico en hospitales.
- Entrada de Kafka, salida de archivo. Un segundo tipo de origen y destino.
Para obtener información general sobre modos, estado y conectores, consulte Tiet · Connect.
Ejemplo 1: HL7 sobre MLLP a un punto final HTTP
Abrir el constructor
- En el menú de navegación de la izquierda, seleccione Tiet · Connect → Network y luego abra Pipes.
- Haz clic en New pipe. El constructor se abre con seis pasos a la izquierda: Basics, Source, Processing, Destinations, Routing, Review. Un indicador de progreso muestra "n/5 secciones listas".
Paso 1: Conceptos básicos
| Campo | Ejemplo | Notas |
|---|---|---|
| Channel name | Demo ADT to webhook | Obligatorio. Exclusivo dentro de su organización. |
| Description | Synthetic ADT messages to a test webhook | Opcional. |
| Tags | hl7, demo | Separados por comas. |
| Enable on create | en | Activado por defecto. |
Paso 2: Fuente
Seleccione Type TCP (MLLP/HL7) (grupo Red). Los campos:
| Campo | Ejemplo | Notas |
|---|---|---|
| Bind Host | 0.0.0.0 | |
| Port | 2575 | Requerido. |
| Framing | MLLP | Elija MLLP. Raw TCP es un oyente diferente, que no es HL7. |
| Delimiter | dejar vacío | Solo TCP sin procesar. |
Paso 3: Procesamiento
Deje la lista vacía. La página muestra "Aún no hay procesadores; los mensajes se transmiten sin transformar". Este ejemplo reenvía el texto HL7 tal como llega.
El paso ofrece once botones bajo Add a transformer or processor: Pipeline, Anonymizer, Filter, Tag Transformer, AI Inference, JavaScript, HL7 to FHIR, FHIR to HL7, XPath, JSONPath y Regex. Cada uno que agregue se convierte en una tarjeta numerada bajo Pipeline order con un interruptor de habilitación, un formulario de configuración (o un cuadro JSON cuando el tipo no tiene un formato conocido) y una lista On error (Stop on error, Skip on error, Fallback on error). Los procesadores se ejecutan de arriba a abajo. Pipeline le pide que seleccione un flujo de trabajo implementado. Antes de confiar en cualquiera de estos, lea HL7 a FHIR: lo que necesita saber: el constructor guarda las tarjetas, pero el motor solo ejecuta algunas de ellas.
Paso 4: Destinos
Haz clic en la lista Type de Destination 1 y elige HTTP / HTTPS. Los campos:
| Campo | Ejemplo | Notas |
|---|---|---|
| URL | https://webhook.example.org/hl7 | Obligatorio. Utilice un receptor de prueba que usted controle. |
| Method | POST | POST, PUT, PATCH u GET. |
| Content-Type | text/plain | El valor predeterminado es application/json. HL7 v2 no es JSON, así que configúrelo. |
| Timeout (ms) | 30000 | |
| Auth Type | none | Los valores basic, bearer o api_key requieren que los campos coincidan (nombre de usuario y contraseña, token de portador, encabezado de clave API y valor de clave API). |
| Idempotency Key / Idempotency Header | vacío | Opcional. Envía una cabecera (por ejemplo, Idempotency-Key) para que el receptor pueda descartar los reenvíos duplicados. Con una cabecera y sin clave, Connect utiliza un hash de la carga útil. |
Add destination añade más destinos. Cada destino recibe cada mensaje.
Paso 5: Enrutamiento
Delivery route tiene dos opciones:
- Direct (origen → destino): procesado en esta instancia de Connect. Elija esta opción para el ejemplo.
- On mesh (radios → centro → radios): seleccione un Source spoke y un Destination spoke. Sin radios registrados, la página indica: "Aún no hay radios registrados. Registre un radio en la vista de malla para enrutar este canal a través de la malla".
La API Connect no almacena las opciones de ramificación enviadas desde el formulario del canal. El servidor descarta los valores source_spoke_id y destination_spoke_id de las solicitudes de creación y actualización, ya que solo el punto final de la ruta del hub (token de la malla) puede establecerlos. Por lo tanto, seleccionar ramificaciones en el constructor podría no modificar la ruta. Después de guardar, verifique la ruta en el inspector de tuberías o en la vista de malla antes de confiar en ella.
Processing settings:
| Campo | Por defecto | Significado |
|---|---|---|
| Max threads | 1 | Trabajadores paralelos para el canal. |
| Queue buffer size | 1000 | Tamaño de la cola del canal. Cuando permanece llena, el mensaje se descarta y se marca como Error con Queue full. |
| Preserve per-key order | apagado | Beta. Mantiene los mensajes con la misma clave (HL7 PID-3, asunto FHIR) en orden de llegada en todos los hilos. Al activarlo, se muestra Ordering key source; déjelo vacío para derivar la clave del mensaje. |
Con Max threads por encima de 1 y Preserve per-key order desactivado, se pueden aplicar dos mensajes para el mismo paciente fuera de orden. Para el tráfico ADT, mantenga Max threads en 1, o active el ordenamiento y pruébelo.
El paso también incluye interruptores (Store messages, Encrypt data, Export data, Remove content on complete), un grupo Advanced con Message storage mode, Clear global channel map on redeploy y FHIR batching (ver más abajo) y cuatro cuadros de script (Preprocessing script, Postprocessing script, Deploy script, Undeploy script). Déjelos con sus valores predeterminados para este ejemplo.
Paso 6: Revisión
La vista muestra Canal, Origen, Procesamiento ("Paso directo" cuando está vacío), Destinos y Ruta, cada uno con un botón para volver atrás. Si falta algo, aparece un mensaje que indica qué: "Agregue un nombre de canal para continuar", "Seleccione un conector de origen" o "Agregue al menos un destino".
Haz clic en Create channel. El mensaje dice "Canal creado".
Despliega la tubería
La nueva tubería aparece en Tuberías con la etiqueta de estado Ready: existe, pero aún no está escuchando. Haga clic en la tubería y luego Resume en el pie de página del inspector. La etiqueta cambia a Deployed.
El paso de revisión dice que el canal "se agregará y se desplegará en la malla". En la práctica, Create channel solo lo crea. Despliéguelo con Resume.
Enviar mensaje de prueba
Utilice la interfaz de línea de comandos de simulación desde tietai-simulation-service. Solo envía pacientes sintéticos.
sim-cli hl7 send --host <connect-host> --port 2575 --type ADT^A01 --count 1 --verbose
Opciones verificadas en app/cli/main.py: -H/--host (predeterminado localhost), -p/--port, -t/--type (ADT^A01, ADT^A03, ADT^A04, ADT^A08, ORU^R01, ORM^O01), -n/--count, -r/--rate, -f/--file (su propio archivo; - es stdin), -v/--verbose, --timeout (segundos, predeterminado 10) y --no-ack. El comando envía el mensaje a través de MLLP y verifica el acuse de recibo: AA o CA cuentan como éxito.
El receptor MLLP envía su confirmación AA tan pronto como el mensaje es aceptado en la cola del canal. No espera a que el destino lo reciba. Una confirmación AA de Connect no prueba que el destino lo haya recibido. Consulte los mensajes de la tubería, como se muestra a continuación.
Comprueba el resultado
- Haz clic en la tubería y luego en Messages. Se abrirá un cajón con las pestañas In channel y Dead-letter, cada una con un contador.
- En el In channel, los filtros de estado son All, Sent, Buffered, Queued y Error. El cuadro de búsqueda acepta un ID de mensaje o el nombre del paciente. La lista se actualiza cada 20 segundos.
- Seleccione su mensaje. El panel de detalles muestra el estado, Route, Errors (si corresponde), Headers y Payload (pestañas por cada representación, como Sin procesar, Transformado, Procesado, Respuesta).
Lo que debería ver: un mensaje con el estado Sent y el mismo texto HL7 llegando a su webhook.
| Estado | Significado |
|---|---|
| Received | Almacenado a su llegada. |
| Sent | Todos los destinos lo aceptaron. |
| Buffered | Los destinos lo aceptaron, pero al menos uno no lo almacenó de forma permanente. Se convierte en Enviado cuando el destino lo confirma. No es lo mismo que Enviado. |
| Queued | Se entrega al procesador de lotes FHIR (ver procesamiento de lotes FHIR más abajo) y espera la respuesta del servidor FHIR. Se convierte en Enviado o Error. |
| Error | Todos los destinos fallaron, la cola estaba llena o el servidor FHIR rechazó un lote. |
Si falla uno de los destinos, el mensaje seguirá mostrando "Enviado" (o "Almacenado en búfer") y la lista de errores indicará "Éxito parcial: ...". Consulte esta lista cuando parezca que faltan datos en un destino. La lista Recent messages del inspector de tuberías muestra los últimos seis.
Gestionar los fallos
Un intento de entrega fallido deja el mensaje en estado Error. Para verlos todos, abra la pestaña Dead-letter del cajón (esta tubería) o Tiet · Connect → Network → DLQ (todas las tuberías).
- Modo independiente: la vista de mensajes no entregados es de solo lectura. Indica: «Solo lectura: este Connect se ejecuta en modo independiente, que no puede reproducir ni descartar mensajes no entregados». Solucione el problema y vuelva a enviar el mensaje desde el origen. En la pestaña In channel, Discard (y luego Delete) elimina el registro del mensaje.
- Modo Hub: seleccione una carta no entregada y elija Replay, o Discard con un motivo. Replay page reintenta todas las cartas no entregadas en la página. En la consola de DLQ también puede seleccionar varias, y Expire old elimina los registros antiguos resueltos o descartados.
Fallos comunes:
| Lo que ves | Causa y solución |
|---|---|
| La tubería permanece Ready | Se creó pero no se desplegó. Haga clic en Resume. |
| El remitente no puede conectarse | La conexión está Ready o en pausa, o el puerto 2575 no está disponible. Reanude la conexión y compruebe la ruta de red. |
Mensaje Error, el texto comienza HTTP request failed with status | El destino respondió con un estado distinto de 2xx. El texto incluye el cuerpo de la respuesta. Corrija la URL, las credenciales o el tipo de contenido. |
Mensaje Error, texto HTTP request failed: | No se pudo alcanzar el destino (DNS, TLS, tiempo de espera agotado). |
Mensaje Error, el texto comienza FHIR server rejected the transaction o BATCH_TIMEOUT | Procesamiento por lotes FHIR: el servidor rechazó el lote o no respondió. Lea los códigos de error en el texto y verifique la propiedad del token de portador. |
Mensaje Error, texto Queue full | Ver Queue buffer size y Max threads. |
Mensaje Error, texto All destinations failed: ... | El prefijo del error. Los nombres que aparecen después indican qué destino falló. |
| Etiqueta de tubería Errors recorded o High error share | Los contadores son acumulativos desde su creación. Abrir Messages → Error. |
Ejemplo 2: Kafka a un archivo
Esto muestra un segundo origen y destino y no necesita un receptor HTTP.
- Conceptos básicos: nombre
Demo Kafka to file. - Fuente: Type
Apache Kafka. Campos: Brokers (obligatorio, separado por comas, por ejemplokafka.example.org:9092), Topic (obligatorio,sim.inbound), Consumer Group (tietai-connect). - Procesando: vacío.
- Destinos: Type
File System. Campos: Directory (obligatorio,/data/outgoing), Filename Pattern (msg_${timestamp}.txt), Append (desactivado), Create Dirs (activado), File Mode (0644). El directorio está en el servidor Connect. - Enrutamiento: Direct. Review → Create channel, luego Resume.
- Enviar un registro de prueba:
sim-cli kafka send --bootstrap kafka.example.org:9092 --topic sim.inbound --format hl7v2 --count 3
--format es hl7v2, fhir, raw o auto; --key establece la clave de registro (predeterminado: el MRN del paciente). Abrir Messages → In channel: tres mensajes y tres archivos en /data/outgoing.
De HL7 a FHIR: todo lo que necesitas saber.
El constructor tiene una entrada HL7 to FHIR en el paso Procesamiento y un tipo de destino FHIR REST Esto es lo que hace el código Connect, comprobado en channel_engine.go, internal/transformers/transformer.go, internal/connectors/http.go y fhir_batcher.go.
1. La entrada del procesador. El constructor permite agregar una tarjeta HL7 to FHIR y la guarda en la lista de procesadores del canal, pero el motor no la ejecuta. La cadena de procesadores del motor (initProcessorChain, processors.NewDefaultRegistry) solo conoce cuatro procesadores DICOM: filter, anonymizer, tag-transformer y ai-inference, y los aplica solo al contenido DICOM JSON. Cualquier otro tipo de procesador (incluidos hl7_to_fhir, fhir_to_hl7, javascript, xpath, jsonpath, regex) hace que la cadena no se construya, y Connect registra "Error al construir la cadena de procesadores" en el servidor y omite toda la cadena, incluidos los procesadores DICOM en la misma lista. El constructor también guarda tag_transformer y ai_inference con guiones bajos, que el registro tampoco reconoce. Solo Pipeline (hydra_pipeline) se ejecuta en su propia ruta, y solo cuando el servidor Connect tiene HYDRA_API_URL configurado y CONNECT_AGENTIC_PROCESSORS_ENABLED no es falso. El motor ejecuta la conversión de HL7 a FHIR solo cuando la propiedad del canal transform_to_fhir es true (el canal HL7 con Connect la establece). El constructor no tiene un campo para esa propiedad. Si necesita la conversión en un canal, establezca la propiedad a través de la API del canal o utilice la ruta de flujo de trabajo en la Receta: ADT a FHIR. Para los resultados de laboratorio de ORU^R01, la propiedad transformer_type establecida en HL7_ORU_TO_FHIR (con transformer_options) selecciona una asignación que reconoce el orden que produce un paquete de transacciones y rechaza el mensaje en lugar de reenviar HL7 sin procesar. Pruebe con un mensaje sintético y lea la pestaña Payload antes de confiar en cualquier conversión.
2. El tipo de paquete. Con la conversión predeterminada HL7_TO_FHIR, el paquete que produce tiene type: "collection", con entradas que tienen fullUrl pero no request. Eso no es un paquete de transacción.
3. El destino REST de FHIR. FHIR REST es el conector HTTP con otro nombre (fhir_rest se asigna a HTTP). Envía el cuerpo del mensaje, sin cambios, a FHIR Server URL con el Method que elegiste (POST o PUT), y con Content-Type: application/fhir+json a menos que lo anules. No convierte un Bundle de colección en una transacción. Un servidor FHIR que espera una transacción o lote en su URL base rechazará un Bundle de colección, y el mensaje muestra Error con HTTP request failed with status ... y el texto del servidor.
4. Procesamiento por lotes FHIR. En el paso 5, active FHIR batching y establezca FHIR server URL (el procesamiento por lotes no funciona sin él). Campos: Batch size, Batch timeout (s), Max concurrent batches, FHIR server URL. Cuando el tipo de datos del motor es FHIR, los recursos se recopilan y se publican como un paquete de transacciones en esa URL. Un recurso simple o una entrada de paquete de recopilación se convierte en una entrada POST para su tipo de recurso; un paquete de transacciones cuyas entradas ya contienen request se pone en cola entrada por entrada sin cambios. Dejar un campo de tamaño vacío utiliza los valores predeterminados del motor: 25 recursos, 5 segundos, 20 lotes concurrentes. El procesador por lotes omite los conectores de destino:
- El mensaje muestra Queued hasta que el servidor FHIR responde. Una respuesta 2xx lo convierte en Sent. Un rechazo o un fallo de transporte lo convierte en Error, con un texto como "El servidor FHIR rechazó la transacción (HTTP 400): ...". Si no llega ninguna respuesta a tiempo, Connect lo marca como Error con
BATCH_TIMEOUT(tiempo de espera del lote más aproximadamente un minuto) y el mensaje se puede reprocesar; - La autenticación no es un campo del constructor. El procesador por lotes envía
Authorization: Bearer ...solo cuando se establece la propiedad del canalfhir_bearer_token_env(el nombre de una variable de entorno en el servidor Connect) ofhir_bearer_tokenSin ella, Connect registra una advertencia y envía la transacción sin encabezado de autenticación. Siempre envíaX-Organization-ID,Content-TypeyAccept: application/fhir+json.
Configure la propiedad del token a través de la API del canal antes de dirigir el procesamiento por lotes a un servidor FHIR que necesite un token.
Si necesita una ruta HL7 a FHIR verificada hoy mismo, créela como un flujo de trabajo con los nodos hl7-to-fhir y fhir-crud Esa ruta publica un paquete de transacciones. Consulte la receta: ADT a FHIR.
Cambiar o quitar una tubería
- Edit en el inspector de tuberías abre un panel lateral para nombre, ruta, destinos y transformaciones. Full editor abre los mismos seis pasos con los valores guardados; el botón de guardar dice Save changes.
- Pause despliega. Nada escucha hasta que tú Resume.
¿Qué hacer a continuación?
- Tiet · Connect: modos, estado, conectores y límites.
- Receta: De ADT a FHIR: la ruta de flujo de trabajo para la misma entrada.
¿Algo no está claro? Envíe sus comentarios sobre la documentación por correo electrónico..
