T4.1: Traces Patient Data Flow

Overview

The Edge Gateway is the entry point for clinical data into the UCR federation. Understanding the complete data flow from inbound message to stored streamlet is essential for troubleshooting data issues, planning customizations, and verifying that data is correctly ingested. Each step in the flow performs a specific function, and problems at any step can result in missing or incorrect patient data.

Inbound Message Reception

Clinical data arrives at the Edge Gateway through various channels:

• HL7 v2.x messages: ADT (admission/discharge/transfer), ORU (results), ORM (orders), MDM (documents)
• CDA documents: Received via file drop, web service, or IHE XDS.b transactions
• Custom feeds: Proprietary formats from specific source systems

The Business Service component is configured to listen on a specific port or monitor a directory for incoming data. It wraps the raw message into an internal request object and passes it to the production.

Routing and Business Process

The Business Process (Router) receives the request from the Business Service and applies routing rules to determine where the message should be sent:

• Message type routing: different paths for ADT, ORU, ORM messages
• Content-based routing: rules that inspect message fields to make routing decisions
• Default routing: standard path for messages that do not match specific rules

The router may send the message to one or more Business Operations for processing.

DTL Transformation

Data Transformation Language (DTL) transforms convert the source message format into the HealthShare SDA format:

• HL7 v2.x fields are mapped to SDA properties
• Coded values may be translated to standard terminologies
• Patient demographics, encounters, diagnoses, procedures, medications, lab results, and other clinical data are extracted and structured
• Custom DTLs can be added to handle site-specific data elements or non-standard message formats

SDA Storage in the ECR

The transformed SDA data is stored in the Edge Clinical Repository (ECR) as streamlets:

• Each clinical data category (diagnosis, medication, lab result, etc.) is stored as a separate streamlet type
• Streamlets are associated with the patient's medical record at the Edge Gateway
• The ECR provides the local store of clinical data before it is aggregated at the Hub
• Streamlet storage triggers notifications to the Hub for patient identity registration and document availability

---

Overview

The Hub (Registry) serves as the central coordination point for the UCR federation. It receives patient identity notifications from Edge Gateways, processes them through the MPI for matching and cross-referencing, manages consent policies, and maintains the document registry. Understanding the Registry data flow is critical for troubleshooting issues that span multiple Edge Gateways or involve patient identity, consent, and data aggregation.

Patient Identity Flow

1. Edge Gateway sends a patient identity notification to the Hub (triggered by new or updated patient data) 2. The Hub's Business Service receives the notification 3. The notification is routed to the MPI Manager Business Process 4. The MPI evaluates the patient identity against existing records using matching algorithms 5. If a match is found, the identifiers are linked; if no match, a new MPI record is created 6. Cross-reference entries are updated to reflect the linked identities

Consent Policy Evaluation

• When a data access request arrives at the Hub, consent policies are evaluated
• The consent engine checks whether the requesting user or organization has permission to access the patient's data
• Consent policies may be based on patient opt-in/opt-out decisions, organizational agreements, or regulatory requirements
• The evaluation result (permit or deny) determines whether the requested data is returned

Document Registration and Aggregation

• Edge Gateways register document metadata with the Hub's XDS Document Registry
• The Registry maintains an index of all available clinical documents across the federation
• The ODS aggregates clinical data from multiple Edge Gateways for a unified patient view
• Aggregation involves merging streamlets from different sources based on MPI-linked patient identities

---

Accessing Visual Trace

1. Open the Management Portal and navigate to the Edge Gateway namespace 2. Go to Ensemble > View Trace or access from the Message Viewer page 3. Search for messages by session ID, date range, source, target, or status 4. Click on a message session to open the Visual Trace diagram

Reading Trace Diagrams

• The trace displays a vertical timeline of message exchanges between production components
• Each arrow represents a message sent from one component to another
• Components are shown as columns (Business Service, Business Process, Business Operation)
• The chronological order flows from top to bottom
• Hover over arrows to see timestamps and message types
• Click on an arrow to view the full request or response message content

Identifying Transformation Steps

• DTL transformations appear as steps within Business Process or Business Operation components
• The trace shows both the input message (before transformation) and the output message (after transformation)
• Compare input and output to verify that transformations are mapping data correctly
• Look for missing or incorrectly mapped fields in the transformed output

Spotting Errors in the Flow

• Errors are indicated by red icons or status markers in the trace
• Click on the error indicator to see the full error message and stack trace
• Common errors include: DTL mapping failures, validation errors, connection timeouts, and routing rule mismatches
• The Event Log provides additional context for errors seen in the trace
• Check the status column in Message Viewer for messages that completed with errors or warnings

---

Tracing MPI Operations

1. Access the Visual Trace on the Hub namespace 2. Search for patient identity notification messages from Edge Gateways 3. Follow the notification through the MPI Manager Business Process 4. Observe the matching algorithm evaluation: which criteria were applied and what scores were produced 5. Verify whether the patient was matched to an existing record or a new record was created 6. Check cross-reference updates to confirm correct identity linking

Tracing Consent Evaluations

• Locate data access request messages in the Hub's Message Viewer
• Open the Visual Trace to see the consent evaluation step
• The trace shows which consent policies were evaluated and the result (permit/deny)
• Verify that the correct policies are being applied for the requesting user and patient
• Check for policy configuration errors that may cause unexpected permit or deny decisions

Tracing Document Registry Transactions

• Follow XDS Register Document Set transactions from Edge Gateways to the Hub
• Verify that document metadata is correctly registered in the XDS Registry
• Trace XDS Query transactions from Access Gateways to the Hub to verify document discovery
• Check for metadata validation errors that may prevent document registration

---

Identifying Where Custom DTLs Are Needed

• Review the existing DTL transformations to understand current mapping logic
• Identify source data fields that are not being mapped to SDA properties
• Determine if non-standard HL7 segments or fields (Z-segments) need custom handling
• Check if site-specific coded values require translation before storage
• Create custom DTL classes that extend or override default transformations

Where Routing Rules Should Be Added

• Analyze the current routing configuration to understand default message paths
• Identify message types or content patterns that require special handling
• Add routing rules to direct specific messages to custom Business Operations or transformations
• Configure content-based routing for messages that need conditional processing
• Test routing changes with representative message samples

Gap Analysis Process

1. Document the current data flow behavior (what data comes in, how it is transformed, where it is stored) 2. Document the desired behavior (what additional data should be captured, what transformations are needed) 3. Compare the two to identify specific gaps 4. Map each gap to a customization point in the production (DTL, routing rule, Business Operation) 5. Prioritize customizations based on impact and complexity

---

Complete Path Overview

The complete path from an inbound HL7 message to stored streamlets follows these steps: 1. HL7 Business Service receives the raw HL7 message on a configured TCP port (e.g., EnsLib.HL7.Service.TCPService) 2. HL7 Router (Business Process) evaluates the message type (MSH-9) and applies routing rules 3. HL7-to-SDA DTL (Data Transformation) converts HL7 segments into SDA format 4. SDA Container holds the structured clinical data (patient demographics, encounters, diagnoses, results) 5. Streamlet Storage persists individual clinical data elements as streamlets in the ECR database

Examining Each Step

Step 1 - HL7 Business Service:

• Configured with the TCP port, acknowledgment mode, and message schema
• Validates the incoming HL7 message structure
• Creates an EnsLib.HL7.Message object and sends it to the configured target (router)

Step 2 - HL7 Router:

• Evaluates routing rules based on MSH-9 (Message Type), MSH-4 (Sending Facility), and other fields
• Routes ADT messages to patient registration processing
• Routes ORU messages to result processing
• Routes ORM messages to order processing

Step 3 - HL7-to-SDA DTL:

• Maps PID segment fields to SDA Patient demographics
• Maps PV1/PV2 segments to SDA Encounter properties
• Maps OBX segments to SDA LabResult or Observation properties
• Maps DG1 segments to SDA Diagnosis properties
• Maps RXA/RXE segments to SDA Medication properties
• Handles repetitions, coded values, and composite fields

Step 4 - SDA Container:

• The SDA Container is an XML structure that holds all clinical data elements
• Each data category (Patient, Encounter, LabResult, Diagnosis, etc.) has its own SDA class
• The container validates the transformed data before storage

Step 5 - Streamlet Storage:

• Each clinical data element from the SDA container is stored as a separate streamlet
• Streamlets are typed (LabResult streamlet, Diagnosis streamlet, Medication streamlet, etc.)
• Streamlets are linked to the patient's MPIID (or local MRN at the Edge)
• Storage triggers notifications to the Hub for aggregation

---

Systematic Troubleshooting Approach

When patient data is expected but not visible in the Edge Gateway or Clinical Viewer, follow a systematic approach to identify the root cause:

Step 1 - Check Visual Trace

• Search for the specific message session in the Message Viewer
• If the message is not found, the data never arrived at the Edge Gateway (check the source system and network connectivity)
• If the message is found, open the Visual Trace to see how far it progressed through the production
• Look for error indicators at any step in the flow

Step 2 - Review Event Log

• Open Ensemble > Event Log in the Management Portal
• Filter by date range, component name, or error severity
• Look for error or warning entries that correspond to the time the data was expected
• Common issues: connection refused, message validation failure, DTL compilation error, timeout

Step 3 - Verify Routing Rules

• Confirm that routing rules include the specific message type and trigger event
• Check for overly restrictive routing conditions that might exclude the message
• Verify that the default routing path handles unexpected message types
• Test the routing rules with a sample message

Step 4 - Inspect Transformation Outputs

• In the Visual Trace, examine the DTL input and output
• Look for fields that are present in the input but missing from the output (mapping gap)
• Check for DTL errors that cause the transformation to fail silently
• Verify that coded values are being translated correctly

Step 5 - Check Consent and MPI

• If data is stored at the Edge but not visible in the Clinical Viewer, check consent policies
• Verify that the patient has been matched in the MPI (unmatched patients may not appear in aggregated views)
• Confirm that the facility and assigning authority are correctly configured
• Check for MPI matching failures that prevent patient identity linking

---

Checking ECR Data

1. Access the Edge Gateway namespace in the Management Portal 2. Navigate to the ECR viewer or query tool 3. Search for the patient by MRN or other identifier 4. Verify that the expected streamlets are present (diagnoses, medications, lab results, encounters) 5. Check streamlet content for completeness and accuracy 6. Compare the stored data against the original source message

Verifying Patient Linkage at the Registry

1. Access the Hub namespace in the Management Portal 2. Open the MPI viewer or search tool 3. Search for the patient by identifier from the Edge Gateway 4. Verify that the patient has cross-reference entries linking identifiers from all contributing facilities 5. Confirm that the MPIID is correctly assigned 6. Check for duplicate MPI records that may indicate matching failures

Confirming ODS Aggregation

• The ODS (Operational Data Store) at the Hub aggregates data from all Edge Gateways
• Search for the patient in the ODS viewer to see the aggregated clinical record
• Verify that data from all contributing facilities is present
• Check for discrepancies between Edge Gateway data and the aggregated view
• If data is missing from the ODS, check the aggregation process for errors

Data Completeness Checks

• Compare the number of streamlets at the Edge with the number expected based on source data volume
• Verify that all clinical data categories are represented (not just demographics)
• Check date ranges to confirm that recent data has been ingested
• Use reports or queries to identify patterns of missing data (e.g., all lab results from a specific date are missing)
• Run data quality reports if available

End-to-End Verification

1. Send a test message from the source system (or replay a known message) 2. Verify receipt at the Edge Gateway Business Service 3. Confirm routing to the correct processing path 4. Verify DTL transformation output 5. Check streamlet storage in the ECR 6. Confirm patient identity notification to the Hub 7. Verify MPI matching and linking 8. Confirm data appears in the ODS aggregated view 9. Access the Clinical Viewer and verify the data is displayed correctly

---