T3.3: Uses Message Viewer

Configuration Overview

The Message Viewer provides numerous search configuration options that significantly impact both search performance and result usability. Understanding how to optimize these settings for different troubleshooting scenarios improves efficiency.

Sort Order

Sort Order determines whether results appear with the oldest messages first (ascending) or newest messages first (descending). For investigating historical issues or understanding how a problem developed over time, ascending order is appropriate. For troubleshooting recent production issues or monitoring current activity, descending order brings the most recent messages to the top. Most troubleshooting scenarios benefit from descending order since you're typically investigating problems that occurred recently.

Page Size

Page Size controls how many results display per page. Smaller page sizes (10-25 messages) load faster and are easier to scan visually. Larger page sizes (100+ messages) reduce paging through results but may load slowly if messages are large or complex. For targeted searches expected to return few results, larger page sizes are efficient. For broad searches that might return thousands of results, smaller page sizes prevent browser performance issues.

Time Format

Time Format affects how timestamps display in search results. The default format shows only time (hours, minutes, seconds), which is sufficient when searching within a specific date range. The "Complete" format shows both date and time, which is essential when search results span multiple days or when you need to correlate messages with external system logs that include dates. For troubleshooting scenarios involving specific incidents at known times, the Complete format provides necessary context.

Practical Impact

These configuration options are not just cosmetic preferences; they directly impact troubleshooting workflow. Inappropriately configured settings can hide relevant messages off the first page, make timestamp interpretation difficult, or cause performance issues with large result sets. Take a moment to configure search options appropriately before executing searches, especially when investigating complex issues.

Indexed Fields for Performance

Basic search criteria provide fast, efficient message searches by querying only indexed fields in the message header. Understanding the capabilities and limitations of basic criteria is essential for effective message investigation.

All basic criteria fields are indexed in the InterSystems IRIS database, meaning searches execute quickly even across millions of messages. The indexing applies to Status, Type, TimeCreated, MessageId, Source, and Target fields. This makes basic criteria appropriate for initial searches to narrow down the message population before applying more complex extended criteria.

Header-Only Limitation

The critical limitation of basic criteria is that they query only the message header (Ens.MessageHeader), not the message body content. You cannot search for HL7 field values, patient names, or other message content using basic criteria alone. For content searches, you must use extended criteria (covered separately).

AND Logic

Basic criteria combine using AND logic exclusively. When you specify Status=Error AND Type=Request AND Source=MyService, only messages matching all three conditions appear in results. This differs from extended criteria, which allow OR logic combinations. The AND-only logic means basic criteria are narrowing filters; each additional criterion reduces the result set.

Status Filter

The Status filter is frequently misunderstood. Status=Error shows messages with ErrorStatus populated, which typically includes response messages that contain error information. If a Business Operation fails to send to an external system, the response message has Status=Error. However, for resending, you typically want the original request message, not the error response. Understanding this distinction prevents selecting the wrong messages for resend operations.

Type Filter

The Type filter defaults to "Session Start", showing only the first message in each session. This default often causes confusion because users expect to see all messages but see only one per session. For most troubleshooting scenarios, change Type to "All" to see request, response, and session start messages. Use Type=Request specifically when searching for messages to resend.

Time and ID Range Filters

Time and ID range filters (StartTime/EndTime, StartId/EndId) provide two approaches to limiting search scope. Time ranges are intuitive when you know when an incident occurred. ID ranges are useful when you have specific message IDs from logs or when investigating a specific batch of messages. The filters persist between page visits, so remember to use Reset to clear them when starting a new search.

Extended Criteria Overview

Extended search criteria provide powerful capabilities beyond basic header searches, enabling searches within message content, complex logical combinations, and optimized indexed searches for HL7 fields. Mastering extended criteria is essential for investigating complex production issues.

AND/OR Logic

Extended criteria support both AND and OR logic operators, allowing complex search conditions like (Status=Error OR Status=Suspended) AND Source=MyService. This flexibility enables sophisticated queries that basic criteria cannot express. You can add multiple extended criteria and combine them using parentheses to control evaluation order.

Header Field

Header Field extended criteria allow searching any property of the Ens.MessageHeader class, including properties not exposed in basic criteria. While basic criteria cover the most common header fields, Header Field extended criteria access additional properties like ReturnQueueName, Priority, or custom header extensions. This is valuable for advanced troubleshooting scenarios requiring access to less common header properties.

Body Property

Body Property extended criteria enable searching within message content for business message classes. When you select Body Property, you must specify the message class (e.g., Ens.AlertRequest, Ens.StringContainer, or custom message classes). The search then allows selecting properties of that class from a dropdown. For example, searching Ens.AlertRequest messages, you can filter on AlertText property to find alerts containing specific error keywords.

VDoc Property Path

VDoc Property Path provides specialized search capabilities for virtual document types like HL7 messages (EnsLib.HL7.Message). This search type requires specifying the Class (EnsLib.HL7.Message) and DocType (e.g., 2.5:ADT_A01). The DocType selection populates the Property Path dropdown with HL7 schema fields like PID:3(1).1 (patient medical record number). This allows precise searches for HL7 messages containing specific field values without requiring custom search tables.

VDoc Segment Field

VDoc Segment Field enables searching repeating segments and fields that may appear multiple times in a message. For example, insurance information may repeat in IN1 segments. VDoc Segment Field allows using the Contains operator to search across all repetitions, finding messages where any occurrence matches the criteria.

Search Table Field

Search Table Field provides the fastest method for searching HL7 content by leveraging pre-built indexes. When you create a search table class (subclass of EnsLib.HL7.SearchTable) and assign it to components, specified HL7 fields are indexed as messages pass through. Search Table Field criteria query these indexes directly, providing performance comparable to basic criteria even when searching message content.

Purpose

Search tables provide a mechanism for indexing specific HL7 message fields, enabling fast content-based searches without scanning every message. Implementing search tables involves a multi-step process that must be followed carefully.

Step 1: Create the Class

The first step is creating a search table class as a subclass of EnsLib.HL7.SearchTable. This is typically done in VS Code or Studio using standard class definition syntax. The class name should reflect its purpose, such as Package.ADTSearchTable or Package.PatientSearchTable, following your organization's naming conventions.

Step 2: Define SearchSpec

Within the search table class, you define an XData block named SearchSpec that lists the HL7 fields to index. The SearchSpec uses XML syntax to specify field paths like <Item DocType="2.5:ADT_A01" PropPath="PID:3(1).1" PropName="MRN" />. Each Item element defines one indexed field, including the DocType it applies to, the property path in the HL7 message, and a PropName you'll use when searching. You can define multiple fields across multiple DocTypes in a single search table.

Step 3: Compile

After defining the class, you must compile it to make it available to the production. Compilation validates the XData syntax and creates the necessary database structures. Compilation errors typically indicate syntax issues in the SearchSpec XML or invalid property paths.

Step 4: Assign to Components

The next step is assigning the search table to HL7 components (Business Services, Business Processes, or Business Operations). In the component settings, set the SearchTableClass parameter to the full class name (e.g., Package.ADTSearchTable). Once assigned, any new messages processed by that component are automatically indexed according to the SearchSpec definition. The indexing happens transparently during message processing.

Step 5: Index Historical Messages

However, messages processed before the search table was assigned are not automatically indexed. To index historical messages, you must explicitly run the BuildIndex() method. This is done through the terminal or a test method using the syntax ##class(Package.SearchTableClass).BuildIndex(). This method scans all messages associated with components using the search table and builds the index retroactively. For large message volumes, this can take significant time and database resources.

Using Search Tables

Once the search table is populated, you use Search Table Field extended criteria in the Message Viewer, selecting the search table class and the PropName defined in the SearchSpec. Searches against indexed fields execute with performance comparable to basic criteria, even though they're searching message content.

Resend Options Overview

The Message Viewer provides multiple resend options, each suited to different troubleshooting and recovery scenarios. Understanding when to use each option and their implications is critical for production support.

Standard Resend

The standard Resend button sends selected messages to their original targets within the original session. When you resend a message this way, the resent message appears in the same Visual Trace session as the original, making it easy to compare original and resend processing. This is the most common resend option, used when messages failed due to temporary issues (external system downtime, network errors) that have since been resolved. You can select multiple messages and perform a mass resend, useful for recovering from extended outages.

Edit and Resend

Edit and Resend is available only when exactly one message is selected. It opens an interface where you can modify the message content before resending. This is valuable when messages failed due to invalid data that can be corrected. For example, if an HL7 message contains an invalid patient ID format, you can correct the field value and resend. The edited message creates a new message with the modified content. Use this option cautiously in production environments, as manual data modification can introduce errors or compliance issues.

New Target

The New Target option allows resending messages to a different component than the original target. This is valuable in several scenarios: after production updates where new processing components are added, when messages need reprocessing through corrected transformation logic, or when routing a subset of messages to a special handling component. When you select New Target, you choose the destination component from a dropdown of all available Business Processes and Business Operations. The resent messages route to this new target instead of the original.

Resubmit at Head of Queue

Resubmit at head of queue places resent messages at the front of the target component's processing queue rather than at the end. This is useful when resending urgent messages that need immediate processing, or when messages are time-sensitive. Normal resend places messages at the end of the queue, meaning they process after all currently queued messages. Resubmit at head of queue gives resent messages priority.

Important Considerations

An important consideration for all resend operations: only resend request messages, not response messages. When searching for messages to resend, use Type=Request in basic criteria to ensure you're selecting the messages that initiated processing, not the responses they generated. Resending response messages typically has no useful effect and may cause confusion in Visual Trace.

Audit Trail

All resend operations are audited in the InterSystems Audit Database as EnsembleMessageResend events, recording who performed the resend and when. This provides an audit trail for compliance and troubleshooting purposes.

Display Prerequisites

The Message Viewer occasionally fails to display messages correctly, showing errors or blank content. Understanding the prerequisites for message display enables rapid resolution of these issues.

Message Class Compilation

The most fundamental requirement is that the message class must be compiled and available in the current namespace. When you select a message in search results, the Message Viewer instantiates the message object using the class name stored in the message header. If that class doesn't exist or isn't compiled, the viewer cannot display the message, typically showing an error like "Class does not exist." This commonly occurs after namespace migrations, when viewing messages in a namespace different from where they were created, or after class deletions. The solution is to compile the message class in the current namespace.

DocType Definition

For HL7 messages (EnsLib.HL7.Message), the DocType must be defined in the HL7 schema definitions loaded in the namespace. When the Message Viewer displays an HL7 message, it uses the DocType to understand the message structure for the Contents tab. If the DocType isn't found in the schema, the message may display in the Body tab but the Contents tab will show an error or display segments without proper structure. This occurs when messages reference custom DocTypes that haven't been imported, or when viewing messages after schema changes.

Schema Loading

The HL7 schema itself must be loaded in the namespace. InterSystems IRIS includes standard HL7 schemas (2.3, 2.4, 2.5, 2.6, etc.) but custom schemas, Z-segments, and modified schemas must be explicitly loaded. If a message references a schema version or category that's not loaded, the Message Viewer cannot parse the message structure. The solution is to import the necessary schema using the HL7 Schema Structures page in the Management Portal.

Schema Compilation

After importing schemas or making schema changes, you must compile the schema classes. HL7 schemas are represented as class definitions, and like any class, they must be compiled before use. Forgetting this compilation step is a common cause of message display issues after schema updates.

Custom Message Classes

For custom business message classes, ensure all property types and referenced classes are also compiled. If a custom message class references another class that doesn't exist, compilation fails or runtime errors occur during message display.

Troubleshooting Tips

When troubleshooting display issues, check the Event Log for specific error messages that indicate which class or DocType is missing. These error messages typically provide the exact class name or DocType that couldn't be found, pointing directly to the resolution.