T1.3: Designs Custom Schemas

Resumen General

Comprender cuándo se requieren schemas personalizados versus cuándo los schemas estándar son suficientes es una habilidad crítica para el diseño de interfaces HL7. Los schemas personalizados agregan complejidad a tu arquitectura de integración, por lo que solo deben crearse cuando sea genuinamente necesario.

Cuándo NO Se Requieren Schemas Personalizados

Segmentos Opcionales Faltantes

• Los schemas HL7 definen muchos segmentos como opcionales (líneas punteadas o corchetes cuadrados)
• Ejemplo: El segmento PD1 es opcional en mensajes ADT_A01
• Si tu sistema emisor no incluye segmentos opcionales, no se necesita schema personalizado
• El mensaje valida exitosamente contra el schema estándar

Z-Segments Estándar al Final de Mensajes

• Gracias al "-z" en la validación dm-z predeterminada
• El estándar HL7 explícitamente permite Z-segments al final para extensiones específicas del proveedor
• Si no necesitas analizar los campos dentro de esos segmentos, usa schema estándar
• La advertencia de validación "Unrecognized Z Segment found after PV1" es informativa, no un error

Cuándo SE Requieren Schemas Personalizados

Escenario 1: Desviaciones de Estructura de Mensaje

• Cuando segmentos requeridos (como EVN en ADT_A01) faltan en los mensajes que recibes
• Crear un schema personalizado que hace el segmento opcional para tu entorno
• Relaja la validación para que coincida con tu realidad de mensajes actual

Escenario 2: Campos Extra en Segmentos Estándar

• Cuando los proveedores agregan campos personalizados a segmentos (ej., identificadores de paciente propietarios en PID)
• Para analizar estos campos extra en DTLs, debes definirlos en un schema personalizado
• Sin schema personalizado, no puedes referenciar campos por nombre - solo GetValueAt() genérico

Escenario 3: Estructura de Segmento Diferente

• Cuando el orden de campos o la cardinalidad difieren del estándar
• Algunas implementaciones de proveedores reordenan campos o cambian el estado requerido/opcional
• Los schemas personalizados documentan estas variaciones y permiten análisis apropiado

Escenario 4: Análisis a Nivel de Campo de Z-Segment

• Cuando necesitas extraer y procesar datos de Z-segments en un DTL
• Para referenciar ZEN.1 (número de encuentro) o ZPR.2 (NPI de proveedor), los campos deben estar definidos
• Sin schema personalizado, puedes recibir/reenviar pero no analizar campos de Z-segment

Escenario 5: Posiciones de Segmento No Estándar

• Cuando segmentos personalizados aparecen en posiciones no estándar (ej., entre PID y PV1)
• Necesitas schema personalizado para definir dónde pertenecen estos segmentos

Marco de Decisión

• Usar schemas estándar: Los mensajes se ajustan a la estructura estándar, no necesitas analizar campos personalizados
• Crear schemas personalizados: La estructura se desvía del estándar, o necesitas analizar contenido personalizado
• Recuerda: Los schemas personalizados agregan carga de mantenimiento, así que evítalos cuando sea posible

Resumen General

Los schemas personalizados en la implementación HL7 de InterSystems se organizan usando categorías de schema, que proporcionan un poderoso mecanismo de herencia que minimiza el esfuerzo requerido para manejar variaciones específicas del proveedor.

¿Qué es una Schema Category?

Un contenedor para un conjunto completo de definiciones HL7:

• Estructuras de mensajes
• Definiciones de segmentos
• Tipos de datos
• Tablas de códigos

InterSystems IRIS for Health viene con categorías de schema estándar: 2.3, 2.4, 2.5, 2.5.1, 2.6, 2.7 y 2.8.

Nomenclatura de Categoría Personalizada

Buenas convenciones de nomenclatura incluyen la versión base y la fuente de variación:

• "2.5_Epic": Variación personalizada de HL7 2.5 para sistemas Epic
• "2.4_Cerner_Lab": Variación personalizada de HL7 2.4 para interfaces de laboratorio Cerner
• "2.5_LocalHospital": Personalizaciones locales para las necesidades específicas de tu hospital

Modelo de Herencia

El poder de las categorías de schema personalizadas:

• La categoría personalizada "2.5_Epic" hereda de la categoría estándar "2.5"
• Incluye automáticamente todas las estructuras de mensajes HL7 2.5 estándar, segmentos, tipos de datos y tablas
• Solo defines lo que difiere del estándar
• Ejemplo: Si Epic agrega tres campos personalizados a PID e incluye un segmento ZEN, solo defines esas variaciones

Beneficios de Mantenimiento

• Esfuerzo reducido: Solo documenta desviaciones del estándar
• Actualizaciones simplificadas: Al pasar de HL7 2.4 a 2.5, las partes estándar se actualizan automáticamente
• Definiciones de schema mínimas: Todo lo demás viene de la categoría base automáticamente

Asignación de Schema

Las categorías de schema personalizadas se asignan a Business Services a través de la configuración Message Schema Category:

• Cuando el Business Service recibe un mensaje, lo analiza según la categoría de schema especificada
• Afecta tanto la validación (qué es estructura válida) como el análisis (accesibilidad de campos en DTLs)

Alcance de Namespace

• Las categorías de schema tienen alcance de namespace
• El schema personalizado creado en un namespace no está disponible automáticamente en otros
• Necesitas recrear o exportar/importar schemas personalizados en cada namespace según sea necesario

Múltiples Categorías Coexistentes

Múltiples categorías de schema personalizadas pueden coexistir en el mismo namespace:

• "2.5_Epic_Inpatient", "2.5_Epic_Ambulatory", "2.5_Cerner_Lab" - todos en un namespace
• Cada Business Service se asigna a una categoría de schema
• Los mensajes de diferentes fuentes se manejan con las variaciones de schema apropiadas

Jerarquías Multi-Nivel

• La herencia soporta jerarquías multi-nivel (raramente necesario)
• Ejemplo: "2.5_Epic" basado en "2.5", luego "2.5_Epic_Cardiology" basado en "2.5_Epic"
• La mayoría de las organizaciones encuentran suficiente un nivel de personalización

Resumen General

Las definiciones de segmentos personalizados son el corazón de los schemas personalizados, permitiéndote documentar y analizar extensiones específicas del proveedor a mensajes HL7. Comprender cómo definir apropiadamente segmentos personalizados es esencial para manejar interfaces HL7 del mundo real.

Reglas de Nomenclatura de Z-Segment

El estándar HL7 explícitamente permite segmentos personalizados:

• Deben tener nombres de tres letras
• La primera letra debe ser "Z"
• Ejemplos comunes: ZEN (encounter), ZPR (provider), ZPV (visit), ZDX (diagnosis), ZIN (insurance)
• El estándar restringe los Z-segments a aparecer al final de los mensajes

Flexibilidad de InterSystems

Dentro de una categoría de schema personalizada:

• Puedes definir Z-segments en cualquier posición en la estructura del mensaje
• No limitado al final del mensaje
• Esencial cuando los sistemas de proveedores colocan segmentos personalizados en posiciones no estándar
• Ejemplo: Algunas implementaciones de Epic incluyen ZPD entre PID y PV1

Definición a Nivel de Campo

Para cada campo en un segmento personalizado, especificas:

• Número de campo: Posición dentro del segmento (1, 2, 3...)
• El campo 0 siempre es el ID del segmento mismo (como "ZEN")
• Los campos definidos por el usuario comienzan en 1
• Nombre de campo: Identificador descriptivo
• Ejemplo: "Encounter Number" o "Provider NPI"
• Se convierte en parte de la ruta de propiedad en código o DTLs
• Tipo de datos: Qué tipo de datos contiene el campo
• Tipos simples: ST (string), NM (numeric), DT (date)
• Tipos complejos: CX (extended composite ID), XPN (extended person name)
• Afecta cómo se analiza el campo y cómo se accede a los subcomponentes
• Longitud: Longitud máxima del campo
• Informativa y usada para validación cuando se habilitan configuraciones más estrictas
• Cardinalidad: Estado requerido/opcional y repetición
• [0..1]: Opcional, sin repetición
• [1..1]: Requerido, sin repetición
• [0..n]: Opcional, puede repetirse
• [1..n]: Requerido, puede repetirse
• Descripción: Documentación sobre el propósito del campo

Acceso a Campos de Segmento Personalizado

Una vez definido en tu schema:

• Acceder a campos en DTLs usando notación con puntos: source.ZEN.1 o target.ZEN.1
• Sin schema personalizado, debes usar métodos genéricos como GetValueAt("ZEN:1")
• Los segmentos personalizados se convierten en ciudadanos de primera clase en tu entorno de integración

Flujo de Trabajo Práctico

1. Recibir mensajes de muestra del proveedor 2. Identificar Z-segments presentes 3. Documentar estructura de campos (de especificaciones del proveedor o ingeniería inversa) 4. Crear categoría de schema personalizada 5. Definir segmentos personalizados con estructuras de campos 6. Referenciar en reglas de enrutamiento, transformar en DTLs, validar

Mantenimiento

• Los sistemas de proveedores evolucionan, agregando campos o cambiando tipos de datos
• Actualizar definiciones de schema personalizadas cuando cambian las implementaciones del proveedor
• Una buena documentación inicial ayuda a los mantenedores futuros

Resumen General

La capacidad de leer definiciones de estructura de schema HL7 e identificar dónde los mensajes reales se desvían de esas definiciones es una habilidad crítica para especialistas en interfaces HL7. Esta habilidad se usa durante el diseño de interfaces, solución de problemas de errores de validación y creación de schemas personalizados.

Convenciones de Notación de Schema

Notación Basada en Texto

• Corchetes cuadrados [PD1]: Segmento opcional - puede estar presente o ausente
• Sin corchetes (MSH, PID): Segmento requerido - debe estar presente
• Llaves {ROL}: Segmento repetible - cero, una o múltiples instancias
• [{NK1}]: Opcional y repetible

Notación Numérica

• [0..1]: Opcional, sin repetición
• [1..1]: Requerido, sin repetición
• [0..n]: Opcional, repetible
• [1..n]: Requerido, repetible

Diagramas Gráficos

• Líneas sólidas: Segmentos requeridos
• Líneas punteadas: Segmentos opcionales
• Paréntesis o marcadores especiales: Segmentos repetibles

Ejemplo: Estructura ADT_A01 (HL7 2.4)

• MSH: Requerido, único (debe aparecer exactamente una vez)
• EVN: Requerido, único (debe aparecer exactamente una vez)
• PID: Requerido, único (debe aparecer exactamente una vez)
• [PD1]: Opcional, único (puede aparecer cero o una vez)
• [{ROL}]: Opcional, repetible (puede aparecer cero o más veces)
• [{NK1}]: Opcional, repetible (puede aparecer cero o más veces)
• PV1: Requerido, único (debe aparecer exactamente una vez)
• [PV2]: Opcional, único (puede aparecer cero o una vez)

Análisis de Desviaciones

• EVN faltante: Desviación - segmento requerido ausente, error de validación dm-z
• Dos segmentos PV1: Desviación - segmento único repetido, error de validación dm-z
• PD1 faltante: NO es una desviación - PD1 es opcional
• Tres segmentos NK1: NO es una desviación - NK1 es repetible
• PV1 antes de PID: Desviación - el orden de segmentos importa
• Z-segments al final: Permitido por validación dm-z
• Z-segments en medio: Marcados como errores

Qué Verifica la Validación dm-z

A nivel de estructura de segmento:

• ¿Están presentes los segmentos requeridos?
• ¿Los segmentos únicos no están repetidos?
• ¿Es correcto el orden de segmentos?
• ¿Hay segmentos no reconocidos (excepto Z-segments al final)?

Qué NO Verifica dm-z

Validaciones a nivel de campo:

• ¿Están presentes los campos requeridos dentro de los segmentos?
• ¿Los valores de campo exceden las longitudes máximas?
• ¿Los valores de campo se ajustan a las tablas de códigos?
• ¿Son correctos los tipos de datos?

Banderas adicionales como "r" (campo requerido) y "l" (longitud) se usan menos comúnmente.

Enfoque de Diseño de Schema Personalizado

• Objetivo: Hacer que el schema coincida con los mensajes reales que recibes
• Si el proveedor envía consistentemente mensajes sin EVN, crear schema personalizado donde EVN sea opcional
• Permite que los mensajes pasen la validación mientras se habilita el análisis apropiado

Habilidad Clave

Dado un ejemplo de mensaje y definición de schema, identifica:

• Qué segmentos faltan que deberían estar presentes
• Qué segmentos están repetidos que deberían ser únicos
• Qué segmentos aparecen que no están en el schema

Resumen General

La asignación de schema es el mecanismo que conecta tu lógica de procesamiento de mensajes a las definiciones estructurales que habilitan el análisis y la validación. Comprender dónde se asignan los schemas, cómo se usan y qué capacidades habilitan es fundamental para la arquitectura de integración HL7.

Ubicación de Asignación de Schema

Ocurre a nivel de Business Service a través de la configuración "Message Schema Category":

• Especifica qué categoría de schema debe usarse para analizar mensajes entrantes
• Podría ser una categoría estándar como "2.5" o una categoría personalizada como "2.5_Epic"
• Cada mensaje recibido por ese Business Service será analizado según la categoría de schema especificada

Propósitos de Asignación de Schema

1. Habilita Análisis de Mensajes

• El mensaje HL7 sin procesar llega como texto con segmentos separados por retornos de carro y campos por tuberías
• La definición de schema le dice al sistema cómo interpretar esa estructura
• Identifica qué segmento es cuál, cuántos campos tiene cada segmento, qué tipos de datos usan esos campos
• Transforma texto sin procesar en un objeto estructurado con propiedades que pueden accederse por nombre

2. Proporciona Estructura para Validación

• Cuando el mensaje llega a un Business Process con validación habilitada, el motor de validación usa la definición de schema
• Sin asignación de schema, no hay base para la validación

3. Establece DocType

• Formato DocType: "{SchemaCategory}:{MessageStructure}"
• Ejemplo: Business Service con "2.5" recibe ADT_A01, DocType se convierte en "2.5:ADT_A01"
• Usado en toda la production para decisiones de enrutamiento, registro y seguimiento

Sin Asignación de Schema Apropiada

• La validación no puede ocurrir
• Los nombres de campo no pueden usarse en reglas de enrutamiento o DTLs
• Debe usar métodos de acceso de campo genéricos como GetValueAt("PID:3.1")
• Los constraints de reglas de enrutamiento basados en DocType no funcionarán
• Esencialmente trabajando con texto sin analizar en lugar de mensajes HL7 estructurados

Secuencia de Validación

1. Mensaje recibido por Business Service 2. Categoría de schema aplicada inmediatamente para analizar el mensaje 3. Mensaje analizado reenviado al componente destino (típicamente Business Process) 4. Validación ocurre antes de que se ejecuten las reglas de enrutamiento (si está habilitada) 5. Si la validación falla, las reglas de enrutamiento nunca se ejecutan

Consideración de Testing Service

Una fuente común de confusión durante pruebas de interface:

• Testing Service permite enviar manualmente mensajes a componentes
• Al omitir Business Service, debes especificar manualmente DocType en la interfaz de prueba
• Sin especificación de DocType, la validación falla y las reglas de enrutamiento basadas en campos no funcionarán
• Error de prueba más frecuente: copiar contenido del mensaje pero olvidar el campo DocType

Múltiples Asignaciones de Schema

Para productions que manejan múltiples versiones HL7 o variaciones de proveedores:

• Diferentes Business Services con diferentes asignaciones de schema
• Ejemplo: BS_Epic_ADT_TCP usa "2.5_Epic", BS_Cerner_Lab_TCP usa "2.4_Cerner_Lab"
• Cada integración usa el schema apropiado para análisis y validación

Solución de Problemas con Asignación de Schema

• Errores de análisis: Primero verifica la asignación de categoría de schema en Business Service
• Fallos de validación: Verifica que la categoría de schema asignada coincida con la estructura del mensaje real
• Problemas de enrutamiento: Confirma que DocType se está estableciendo correctamente según la asignación de schema