T3.3: Uses Message Viewer

Descripción General de Configuración

El Message Viewer proporciona numerosas opciones de configuración de búsqueda que impactan significativamente tanto el rendimiento de búsqueda como la usabilidad de los resultados. Comprender cómo optimizar estas configuraciones para diferentes escenarios de resolución de problemas mejora la eficiencia.

Orden de Clasificación

El Orden de Clasificación determina si los resultados aparecen con los mensajes más antiguos primero (ascendente) o los más recientes primero (descendente). Para investigar problemas históricos o entender cómo se desarrolló un problema a lo largo del tiempo, el orden ascendente es apropiado. Para resolver problemas de producción recientes o monitorear actividad actual, el orden descendente trae los mensajes más recientes al principio. La mayoría de los escenarios de resolución de problemas se benefician del orden descendente ya que típicamente estás investigando problemas que ocurrieron recientemente.

Tamaño de Página

El Tamaño de Página controla cuántos resultados se muestran por página. Tamaños de página más pequeños (10-25 mensajes) cargan más rápido y son más fáciles de escanear visualmente. Tamaños de página más grandes (100+ mensajes) reducen la paginación a través de resultados pero pueden cargar lentamente si los mensajes son grandes o complejos. Para búsquedas dirigidas que se esperan retornen pocos resultados, los tamaños de página más grandes son eficientes. Para búsquedas amplias que podrían retornar miles de resultados, los tamaños de página más pequeños previenen problemas de rendimiento del navegador.

Formato de Hora

El Formato de Hora afecta cómo se muestran las marcas de tiempo en los resultados de búsqueda. El formato predeterminado muestra solo la hora (horas, minutos, segundos), lo cual es suficiente cuando se busca dentro de un rango de fechas específico. El formato "Complete" muestra tanto fecha como hora, lo cual es esencial cuando los resultados de búsqueda abarcan múltiples días o cuando necesitas correlacionar mensajes con logs de sistemas externos que incluyen fechas. Para escenarios de resolución de problemas que involucran incidentes específicos en horarios conocidos, el formato Complete proporciona el contexto necesario.

Impacto Práctico

Estas opciones de configuración no son solo preferencias cosméticas; impactan directamente el flujo de trabajo de resolución de problemas. Configuraciones inapropiadas pueden ocultar mensajes relevantes fuera de la primera página, hacer difícil la interpretación de marcas de tiempo, o causar problemas de rendimiento con conjuntos de resultados grandes. Toma un momento para configurar las opciones de búsqueda apropiadamente antes de ejecutar búsquedas, especialmente cuando investigas problemas complejos.

Campos Indexados para Rendimiento

Los criterios de búsqueda básicos proporcionan búsquedas de mensajes rápidas y eficientes consultando solo campos indexados en el encabezado del mensaje. Comprender las capacidades y limitaciones de los criterios básicos es esencial para una investigación efectiva de mensajes.

Todos los campos de criterios básicos están indexados en la base de datos de InterSystems IRIS, lo que significa que las búsquedas se ejecutan rápidamente incluso a través de millones de mensajes. La indexación aplica a los campos Status, Type, TimeCreated, MessageId, Source y Target. Esto hace que los criterios básicos sean apropiados para búsquedas iniciales para reducir la población de mensajes antes de aplicar criterios extendidos más complejos.

Limitación de Solo Encabezado

La limitación crítica de los criterios básicos es que consultan solo el encabezado del mensaje (Ens.MessageHeader), no el contenido del cuerpo del mensaje. No puedes buscar valores de campos HL7, nombres de pacientes u otro contenido de mensaje usando solo criterios básicos. Para búsquedas de contenido, debes usar criterios extendidos (cubiertos por separado).

Lógica AND

Los criterios básicos se combinan usando lógica AND exclusivamente. Cuando especificas Status=Error AND Type=Request AND Source=MyService, solo los mensajes que coinciden con las tres condiciones aparecen en los resultados. Esto difiere de los criterios extendidos, que permiten combinaciones con lógica OR. La lógica solo-AND significa que los criterios básicos son filtros de reducción; cada criterio adicional reduce el conjunto de resultados.

Filtro de Estado

El filtro de estado es frecuentemente malentendido. Status=Error muestra mensajes con ErrorStatus poblado, lo cual típicamente incluye mensajes de respuesta que contienen información de error. Si un Business Operation falla al enviar a un sistema externo, el mensaje de respuesta tiene Status=Error. Sin embargo, para reenvío, típicamente quieres el mensaje de solicitud original, no la respuesta de error. Comprender esta distinción previene seleccionar los mensajes incorrectos para operaciones de reenvío.

Filtro de Tipo

El filtro de tipo tiene como predeterminado "Session Start", mostrando solo el primer mensaje en cada sesión. Este predeterminado frecuentemente causa confusión porque los usuarios esperan ver todos los mensajes pero ven solo uno por sesión. Para la mayoría de los escenarios de resolución de problemas, cambia Type a "All" para ver mensajes de solicitud, respuesta e inicio de sesión. Usa Type=Request específicamente cuando buscas mensajes para reenviar.

Filtros de Rango de Tiempo e ID

Los filtros de rango de tiempo e ID (StartTime/EndTime, StartId/EndId) proporcionan dos enfoques para limitar el alcance de búsqueda. Los rangos de tiempo son intuitivos cuando sabes cuándo ocurrió un incidente. Los rangos de ID son útiles cuando tienes IDs de mensaje específicos de logs o cuando investigas un lote específico de mensajes. Los filtros persisten entre visitas a la página, así que recuerda usar Reset para limpiarlos cuando inicies una nueva búsqueda.

Descripción General de Criterios Extendidos

Los criterios de búsqueda extendidos proporcionan capacidades poderosas más allá de las búsquedas básicas de encabezado, permitiendo búsquedas dentro del contenido del mensaje, combinaciones lógicas complejas y búsquedas indexadas optimizadas para campos HL7. Dominar los criterios extendidos es esencial para investigar problemas de producción complejos.

Lógica AND/OR

Los criterios extendidos soportan tanto operadores lógicos AND como OR, permitiendo condiciones de búsqueda complejas como (Status=Error OR Status=Suspended) AND Source=MyService. Esta flexibilidad permite consultas sofisticadas que los criterios básicos no pueden expresar. Puedes agregar múltiples criterios extendidos y combinarlos usando paréntesis para controlar el orden de evaluación.

Header Field

Los criterios extendidos de Header Field permiten buscar cualquier propiedad de la clase Ens.MessageHeader, incluyendo propiedades no expuestas en los criterios básicos. Mientras los criterios básicos cubren los campos de encabezado más comunes, los criterios extendidos de Header Field acceden a propiedades adicionales como ReturnQueueName, Priority o extensiones de encabezado personalizadas. Esto es valioso para escenarios avanzados de resolución de problemas que requieren acceso a propiedades de encabezado menos comunes.

Body Property

Los criterios extendidos de Body Property permiten buscar dentro del contenido del mensaje para clases de mensaje de negocio. Cuando seleccionas Body Property, debes especificar la clase de mensaje (ej., Ens.AlertRequest, Ens.StringContainer o clases de mensaje personalizadas). La búsqueda entonces permite seleccionar propiedades de esa clase desde un menú desplegable. Por ejemplo, buscando mensajes Ens.AlertRequest, puedes filtrar en la propiedad AlertText para encontrar alertas que contengan palabras clave de error específicas.

VDoc Property Path

VDoc Property Path proporciona capacidades de búsqueda especializadas para tipos de documentos virtuales como mensajes HL7 (EnsLib.HL7.Message). Este tipo de búsqueda requiere especificar la Clase (EnsLib.HL7.Message) y DocType (ej., 2.5:ADT_A01). La selección de DocType poblará el menú desplegable de Property Path con campos del esquema HL7 como PID:3(1).1 (número de registro médico del paciente). Esto permite búsquedas precisas de mensajes HL7 que contienen valores de campo específicos sin requerir tablas de búsqueda personalizadas.

VDoc Segment Field

VDoc Segment Field permite buscar segmentos y campos repetitivos que pueden aparecer múltiples veces en un mensaje. Por ejemplo, la información de seguro puede repetirse en segmentos IN1. VDoc Segment Field permite usar el operador Contains para buscar a través de todas las repeticiones, encontrando mensajes donde cualquier ocurrencia coincida con los criterios.

Search Table Field

Search Table Field proporciona el método más rápido para buscar contenido HL7 aprovechando índices pre-construidos. Cuando creas una clase de tabla de búsqueda (subclase de EnsLib.HL7.SearchTable) y la asignas a componentes, los campos HL7 especificados se indexan mientras los mensajes pasan. Los criterios de Search Table Field consultan estos índices directamente, proporcionando rendimiento comparable a los criterios básicos incluso cuando se busca contenido de mensaje.

Propósito

Las tablas de búsqueda proporcionan un mecanismo para indexar campos específicos de mensajes HL7, permitiendo búsquedas rápidas basadas en contenido sin escanear cada mensaje. Implementar tablas de búsqueda involucra un proceso de múltiples pasos que debe seguirse cuidadosamente.

Paso 1: Crear la Clase

El primer paso es crear una clase de tabla de búsqueda como subclase de EnsLib.HL7.SearchTable. Esto típicamente se hace en VS Code o Studio usando la sintaxis estándar de definición de clases. El nombre de la clase debe reflejar su propósito, como Package.ADTSearchTable o Package.PatientSearchTable, siguiendo las convenciones de nomenclatura de tu organización.

Paso 2: Definir SearchSpec

Dentro de la clase de tabla de búsqueda, defines un bloque XData llamado SearchSpec que lista los campos HL7 a indexar. El SearchSpec usa sintaxis XML para especificar rutas de campos como <Item DocType="2.5:ADT_A01" PropPath="PID:3(1).1" PropName="MRN" />. Cada elemento Item define un campo indexado, incluyendo el DocType al que aplica, la ruta de propiedad en el mensaje HL7, y un PropName que usarás cuando busques. Puedes definir múltiples campos a través de múltiples DocTypes en una sola tabla de búsqueda.

Paso 3: Compilar

Después de definir la clase, debes compilarla para hacerla disponible para producción. La compilación valida la sintaxis XData y crea las estructuras de base de datos necesarias. Los errores de compilación típicamente indican problemas de sintaxis en el XML de SearchSpec o rutas de propiedad inválidas.

Paso 4: Asignar a Componentes

El siguiente paso es asignar la tabla de búsqueda a componentes HL7 (Business Services, Business Processes o Business Operations). En la configuración del componente, establece el parámetro SearchTableClass con el nombre completo de la clase (ej., Package.ADTSearchTable). Una vez asignada, cualquier mensaje nuevo procesado por ese componente se indexa automáticamente según la definición de SearchSpec. La indexación ocurre transparentemente durante el procesamiento de mensajes.

Paso 5: Indexar Mensajes Históricos

Sin embargo, los mensajes procesados antes de que se asignara la tabla de búsqueda no se indexan automáticamente. Para indexar mensajes históricos, debes ejecutar explícitamente el método BuildIndex(). Esto se hace a través del terminal o un método de prueba usando la sintaxis ##class(Package.SearchTableClass).BuildIndex(). Este método escanea todos los mensajes asociados con componentes que usan la tabla de búsqueda y construye el índice retroactivamente. Para grandes volúmenes de mensajes, esto puede tomar tiempo significativo y recursos de base de datos.

Uso de Tablas de Búsqueda

Una vez que la tabla de búsqueda está poblada, usas criterios extendidos de Search Table Field en el Message Viewer, seleccionando la clase de tabla de búsqueda y el PropName definido en SearchSpec. Las búsquedas contra campos indexados se ejecutan con rendimiento comparable a los criterios básicos, aunque estén buscando contenido de mensaje.

Descripción General de Opciones de Reenvío

El Message Viewer proporciona múltiples opciones de reenvío, cada una adecuada para diferentes escenarios de resolución de problemas y recuperación. Comprender cuándo usar cada opción y sus implicaciones es crítico para el soporte de producción.

Reenvío Estándar

El botón estándar Resend envía los mensajes seleccionados a sus objetivos originales dentro de la sesión original. Cuando reenvías un mensaje de esta manera, el mensaje reenviado aparece en la misma sesión de Visual Trace que el original, haciendo fácil comparar el procesamiento original y el reenvío. Esta es la opción de reenvío más común, usada cuando los mensajes fallaron debido a problemas temporales (tiempo de inactividad del sistema externo, errores de red) que ya han sido resueltos. Puedes seleccionar múltiples mensajes y realizar un reenvío masivo, útil para recuperarse de interrupciones extendidas.

Editar y Reenviar

Edit and Resend está disponible solo cuando exactamente un mensaje está seleccionado. Abre una interfaz donde puedes modificar el contenido del mensaje antes de reenviar. Esto es valioso cuando los mensajes fallaron debido a datos inválidos que pueden ser corregidos. Por ejemplo, si un mensaje HL7 contiene un formato de ID de paciente inválido, puedes corregir el valor del campo y reenviar. El mensaje editado crea un nuevo mensaje con el contenido modificado. Usa esta opción con cautela en entornos de producción, ya que la modificación manual de datos puede introducir errores o problemas de cumplimiento.

Nuevo Objetivo

La opción New Target permite reenviar mensajes a un componente diferente del objetivo original. Esto es valioso en varios escenarios: después de actualizaciones de producción donde se agregaron nuevos componentes de procesamiento, cuando los mensajes necesitan reprocesamiento a través de lógica de transformación corregida, o cuando se enrutan subconjuntos de mensajes a un componente de manejo especial. Cuando seleccionas New Target, eliges el componente de destino de un menú desplegable de todos los Business Processes y Business Operations disponibles. Los mensajes reenviados se enrutan a este nuevo objetivo en lugar del original.

Reenviar al Principio de la Cola

Resubmit at head of queue coloca los mensajes reenviados al frente de la cola de procesamiento del componente objetivo en lugar de al final. Esto es útil cuando se reenvían mensajes urgentes que necesitan procesamiento inmediato, o cuando los mensajes son sensibles al tiempo. El reenvío normal coloca los mensajes al final de la cola, lo que significa que se procesan después de todos los mensajes actualmente en cola. Resubmit at head of queue da prioridad a los mensajes reenviados.

Consideraciones Importantes

Una consideración importante para todas las operaciones de reenvío: solo reenvía mensajes de solicitud, no mensajes de respuesta. Cuando busques mensajes para reenviar, usa Type=Request en los criterios básicos para asegurarte de que estás seleccionando los mensajes que iniciaron el procesamiento, no las respuestas que generaron. Reenviar mensajes de respuesta típicamente no tiene efecto útil y puede causar confusión en Visual Trace.

Registro de Auditoría

Todas las operaciones de reenvío se auditan en la Base de Datos de Auditoría de InterSystems como eventos EnsembleMessageResend, registrando quién realizó el reenvío y cuándo. Esto proporciona un registro de auditoría para propósitos de cumplimiento y resolución de problemas.

Requisitos Previos de Visualización

El Message Viewer ocasionalmente falla al mostrar mensajes correctamente, mostrando errores o contenido en blanco. Comprender los requisitos previos para la visualización de mensajes permite una resolución rápida de estos problemas.

Compilación de Clase de Mensaje

El requisito más fundamental es que la clase de mensaje debe estar compilada y disponible en el namespace actual. Cuando seleccionas un mensaje en los resultados de búsqueda, el Message Viewer instancia el objeto de mensaje usando el nombre de clase almacenado en el encabezado del mensaje. Si esa clase no existe o no está compilada, el visor no puede mostrar el mensaje, típicamente mostrando un error como "Class does not exist." Esto comúnmente ocurre después de migraciones de namespace, cuando se ven mensajes en un namespace diferente de donde fueron creados, o después de eliminaciones de clases. La solución es compilar la clase de mensaje en el namespace actual.

Definición de DocType

Para mensajes HL7 (EnsLib.HL7.Message), el DocType debe estar definido en las definiciones de esquema HL7 cargadas en el namespace. Cuando el Message Viewer muestra un mensaje HL7, usa el DocType para entender la estructura del mensaje para la pestaña Contents. Si el DocType no se encuentra en el esquema, el mensaje puede mostrarse en la pestaña Body pero la pestaña Contents mostrará un error o mostrará segmentos sin estructura apropiada. Esto ocurre cuando los mensajes referencian DocTypes personalizados que no han sido importados, o cuando se ven mensajes después de cambios de esquema.

Carga de Esquema

El esquema HL7 en sí debe estar cargado en el namespace. InterSystems IRIS incluye esquemas HL7 estándar (2.3, 2.4, 2.5, 2.6, etc.) pero los esquemas personalizados, Z-segments y esquemas modificados deben ser cargados explícitamente. Si un mensaje referencia una versión o categoría de esquema que no está cargada, el Message Viewer no puede analizar la estructura del mensaje. La solución es importar el esquema necesario usando la página HL7 Schema Structures en el Management Portal.

Compilación de Esquema

Después de importar esquemas o hacer cambios de esquema, debes compilar las clases de esquema. Los esquemas HL7 están representados como definiciones de clase, y como cualquier clase, deben ser compilados antes de usarse. Olvidar este paso de compilación es una causa común de problemas de visualización de mensajes después de actualizaciones de esquema.

Clases de Mensaje Personalizadas

Para clases de mensaje de negocio personalizadas, asegúrate de que todos los tipos de propiedades y clases referenciadas también estén compiladas. Si una clase de mensaje personalizada referencia otra clase que no existe, la compilación falla o ocurren errores en tiempo de ejecución durante la visualización del mensaje.

Consejos de Resolución de Problemas

Cuando resuelvas problemas de visualización, revisa el Event Log para mensajes de error específicos que indiquen qué clase o DocType falta. Estos mensajes de error típicamente proporcionan el nombre exacto de la clase o DocType que no pudo ser encontrado, apuntando directamente a la resolución.