T3.2: Uses Visual Trace

Fundamental Concept

The Session ID is a fundamental concept in InterSystems HealthConnect that links related messages together throughout their processing lifecycle. Understanding Session ID is essential for effective use of Visual Trace and message investigation.

Storage Location

Session ID is stored in the message header (Ens.MessageHeader), not in the message body. When the first message in a processing flow enters the production, IRIS assigns it a unique Message ID. This Message ID becomes the Session ID for that initial message and all subsequent messages generated during its processing.

Session ID Inheritance

For example, when a Business Service receives an HL7 ADT message and forwards it to a Message Router, the router creates new messages to send to multiple Business Operations. All these messages receive the same Session ID as the original message, even though each has its own unique Message ID. This allows Visual Trace to group all related messages together, showing the complete processing flow in a single view.

Propagation Across Boundaries

The Session ID remains constant across synchronous and asynchronous message exchanges, through transformations, and across component boundaries. Whether a Business Process calls a Business Operation synchronously or sends an asynchronous request, the Session ID propagates through the entire message chain.

Troubleshooting Usage

When troubleshooting, you can identify the Session ID by viewing any message header in the Message Viewer or Visual Trace. Once you have the Session ID, you can open Visual Trace for that session to see all related messages and their processing sequence. This is particularly valuable when investigating complex routing scenarios or tracking how a single inbound message resulted in multiple outbound messages.

Two-Dimensional Layout

Visual Trace presents message flow using a two-dimensional layout that encodes both temporal and spatial information. Mastering this layout is essential for rapid troubleshooting and understanding message processing patterns.

Vertical Axis: Time

The vertical axis represents time, with messages and events appearing from top to bottom in chronological order. The first message appears at the top, and subsequent processing steps cascade downward. This chronological ordering makes it easy to follow the sequence of operations and identify where processing delays or errors occurred.

Horizontal Axis: Components

The horizontal axis represents component boundaries, with each production component occupying a vertical column. Messages flow between these columns as they move from Business Services through Business Processes to Business Operations. This spatial layout provides instant visual feedback about which components were involved in processing and the direction of message flow.

Icon Types

Icons appearing in each component's column represent different types of events. Message icons show message creation, transmission, and receipt. Event log icons (appearing as small circular icons) represent logged events such as errors, warnings, or informational messages. Rule log icons appear as numbered green icons when routing rules execute.

Clickable Elements

Every icon is clickable, providing detailed information when selected. Clicking a message icon displays the message header, body, and contents in tabs below the trace. Clicking an event icon shows the event text, timestamp, and severity. Clicking a rule execution icon displays which rule was evaluated and which when clause matched.

Visual Patterns

The trace layout makes certain patterns immediately obvious: synchronous calls appear as paired request-response arrows, asynchronous messages show a single arrow with no immediate response, and complex routing scenarios display as one message splitting into multiple downstream messages.

Purpose of Color Coding

Visual Trace uses color coding to distinguish between different message communication patterns, enabling rapid identification of synchronous versus asynchronous processing and potential timing issues.

Synchronous Messages

Synchronous messages appear as colored arrow pairs connecting two components. The request arrow flows from the calling component to the called component, and a response arrow flows back. These arrows share coordinating colors, making the request-response pairing visually obvious. Synchronous communication indicates the calling component waits for the response before continuing processing.

Asynchronous Messages

Asynchronous messages appear as single colored arrows from sender to receiver with no immediate response arrow. This indicates the sender dispatched the message and continued processing without waiting for a reply. Some asynchronous messages may generate responses later, which appear lower in the trace timeline, but there's no visual pairing between the request and delayed response.

One-Way Messages

One-way messages represent fire-and-forget communication where no response is expected or possible. These typically appear as single arrows to Business Operations that perform actions without returning status information.

Gray (Late) Messages

Gray messages indicate late responses that arrived after the calling component stopped waiting. This commonly occurs in two scenarios: First, when a timeout expires before a synchronous response arrives, the calling component gives up waiting. If the response eventually arrives, it appears in gray to indicate it was ignored. Second, when a Business Process makes an asynchronous call but doesn't execute a corresponding synchronous response operation, any response appears in gray because the process isn't waiting for it.

Troubleshooting Benefits

Understanding color coding accelerates troubleshooting by making timing issues, communication patterns, and unexpected late responses immediately visible without requiring detailed message examination.

Icon Overview

Visual Trace displays multiple icon types that represent different aspects of message processing. Understanding what each icon type represents and how to interpret their sequence is essential for effective troubleshooting.

Message Icons

Message icons typically appear as envelope symbols or arrows. These represent actual message objects flowing between components. When you see a message icon in a component's column, it indicates that component created, received, or processed that message. The arrow direction shows message flow, making it easy to trace how data moves through the production.

Event Log Icons

Event log icons appear as small circular icons within component columns. These represent entries in the Event Log, including errors, warnings, informational messages, and trace statements. The icon color and style indicate event severity: red for errors, yellow for warnings, blue for informational messages, and other colors for trace and assert events. Clicking an event icon displays the complete event text, allowing you to see error messages, stack traces, or informational details without leaving Visual Trace.

Rule Log Icons

Rule log icons are distinctive numbered green circles that appear when a routing rule or decision rule executes. The number inside the icon indicates which execution this represents within the session. When multiple routing decisions occur in a session, each receives a sequential number, making it easy to identify the order of rule evaluations. Clicking a rule log icon shows detailed execution information, including which specific rule in the set matched and which when clause triggered.

Icon Sequence

The sequence of icons within a component's column shows the order of operations within that component. For example, you might see a message icon (message received), followed by a rule log icon (routing rule evaluated), followed by multiple message icons (routed messages sent to destinations). This sequence tells the complete story of what the component did and in what order.

Context Interpretation

Icon context is crucial. An error icon in a Business Operation suggests an external system connection issue, while an error in a Business Process might indicate a transformation or logic problem. Reading icons in their component context accelerates root cause identification.

Tab Overview

When you select a message in Visual Trace, three tabs appear below the trace diagram, each providing different perspectives on the message data. Understanding what information each tab contains and when to use each is essential for efficient troubleshooting.

Header Tab

The Header tab displays the message header (Ens.MessageHeader) properties that IRIS automatically creates for every message. This includes Session ID, Message ID, TimeCreated, TimeProcessed, Source configuration name, Target configuration name, Status, ErrorStatus, and other metadata. The header does not contain the actual message content; it contains information about the message's lifecycle and routing. When investigating message flow problems, the Header tab shows you exactly where the message came from (Source) and where it was going (Target), making it easy to verify routing behavior.

Body Tab

The Body tab shows the message body content in its raw form. For HL7 messages, this displays the complete message as a text stream with segment separators. For custom business message classes, it shows the property values. The Body tab is useful when you need to see exactly what data was transmitted, including any formatting or special characters.

Contents Tab

The Contents tab is specifically valuable for HL7 messages (EnsLib.HL7.Message). It presents the parsed HL7 structure in a hierarchical tree view, showing segments, fields, components, and subcomponents. You can expand segments like PID or PV1 to see individual fields, and further expand repeating fields to see multiple occurrences. This parsed view makes it much easier to locate specific data elements than scanning the raw Body tab. For example, to find the patient's medical record number, you can navigate to PID:3(1).1 in the Contents tab rather than parsing the segment separator syntax manually.

HL7 Troubleshooting Tips

When troubleshooting HL7 issues, use the Contents tab to verify that expected data exists in the correct fields, that DocType assignment resulted in proper parsing, and that transformations correctly moved data between fields. The hierarchical view makes field navigation intuitive and reduces errors compared to counting field separators in the raw message.

Alert Visibility

Visual Trace provides complete visibility into alert generation, allowing you to identify not just that an alert occurred, but exactly what triggered it and what information it contains. This is crucial for effective alert investigation and resolution.

Alert on Error

Alerts generated by the "Alert on Error" setting appear in Visual Trace immediately after the error occurs. You'll see an error event icon in the component that experienced the problem, followed by a message icon representing an Ens.AlertRequest flowing to the Ens.Alert component. By clicking the error event icon, you can see the error text and stack trace. By clicking the Ens.AlertRequest message, you can see how that error was packaged into the alert, including alert text, source component name, and associated session ID.

Alert on Bad Message

"Alert on Bad Message" functions similarly but triggers specifically on validation failures in Message Routers. When an HL7 message fails validation, you'll see the message route to the Bad Message Handler (if configured) and simultaneously see an Ens.AlertRequest flow to Ens.Alert. The alert body contains details about the validation failure, including which validation rules failed and information about the invalid message.

Custom Alerts (SendAlert)

Custom alerts created using the SendAlert action in Business Process logic appear as explicit Ens.AlertRequest messages originating from the Business Process. These are distinguishable from automatic alerts because they occur at specific points in the process logic where the developer placed the SendAlert action. The alert text for custom alerts is developer-defined, so it may provide specific context about the business condition that triggered the alert.

Alert Convergence and Investigation

All alert types converge on the Ens.Alert component, making Visual Trace the central location for understanding alert flow. By examining the Ens.AlertRequest message body, you can see the AlertText, SourceConfigName, AlertTime, and associated SessionId. This information allows you to navigate from the alert back to the originating session to investigate the root cause.

Understanding alert patterns in Visual Trace helps identify whether alerts represent one-time errors, recurring issues with specific messages, or systemic problems requiring configuration changes.

Configuration Debugging Overview

Visual Trace excels at identifying production configuration problems by showing exactly where message processing fails and what error messages are generated. Understanding common configuration problem patterns accelerates troubleshooting.

Missing TargetConfigNames

Missing TargetConfigNames manifest in Visual Trace as messages that arrive at a Message Router but don't generate any outbound messages to Business Operations. When you examine the routing rule execution (green numbered icon), the details show that no routing rule matched, or the rule matched but returned no target. This typically indicates routing rule constraints that don't match the incoming message properties, or rules that haven't been updated after production changes. Check the rule log Reason field to see which when clauses were evaluated and why they didn't match.

Missing Message Schema Category

Missing Message Schema Category in HL7 Business Services causes validation and parsing failures. In Visual Trace, you'll see an error event icon immediately after the service receives the message, with an error indicating IRIS couldn't determine the message structure. The Message Schema Category setting tells the Business Service which HL7 schema version to use. Without this setting, IRIS cannot parse or validate incoming messages. The fix is to set Message Schema Category to the appropriate schema (e.g., "2.5" for HL7 v2.5 messages).

Routing Rule Constraint Mismatches

Routing rule constraint mismatches appear when messages reach the Message Router but don't match expected routing rules. The rule log execution shows which rules were evaluated but displays that when clauses failed to match. Common causes include Source constraints that reference non-existent Business Service names, field path constraints using incorrect property paths, or value constraints expecting data that's not present in the message. By examining the message Contents tab alongside the rule log details, you can identify discrepancies between what the rule expects and what the message contains.

Missing DocType

Missing DocType causes multiple problems visible in Visual Trace. Messages without DocType cannot be validated (they automatically route to Bad Message Handler if validation is enabled), cannot be parsed into the proper schema structure (the Contents tab shows generic segments rather than schema-specific structure), and may fail routing rules that access schema-specific fields. The error messages explicitly state "DocType not set" or similar. The fix is to ensure the Business Service assigns DocType using the DocType setting or DocSchemaCategory with DocType expression.

Troubleshooting Efficiency

Visual Trace accelerates configuration troubleshooting by showing not just that an error occurred, but the exact component, the exact message, and the exact error text, allowing you to go directly to the relevant configuration setting.