T2.1: Handles and Transforms Healthcare Data Formats

Overview

The message routing architecture in HealthShare UCR is built on the InterSystems IRIS interoperability framework. At its core, a message router business process evaluates incoming messages against a set of routing rules and directs each message to the appropriate downstream component for processing. This architecture supports the diverse data formats (HL7, x12, CDA, FHIR) that flow through Edge Gateways and the Hub Registry.

Routing rules provide the flexibility to handle different message types, source facilities, and processing requirements without requiring custom code for each scenario. Understanding the routing architecture is essential for configuring data flows that correctly transform and store clinical data.

Router Business Process

• The router is a specialized business process that acts as a message dispatcher
• It receives messages from inbound business services and evaluates them against defined rules
• Based on rule evaluation, messages are sent to one or more target components
• The router itself does not transform data; it determines which transformation or processing path to use
• Multiple routers can exist in a production for different processing stages or message categories

Routing by Message Type and Source

• Message Type Routing: Route HL7 ADT messages to one process and ORU messages to another
• Source Routing: Route messages from Hospital A through one transformation path and Hospital B through another
• Combined Routing: Apply both message type and source criteria for fine-grained routing control
• Default Routing: Messages that do not match any specific rule follow the default path defined in TargetConfigNames
• Priority Routing: Rules can be ordered by priority so that the most specific rules are evaluated first

Rule Evaluation Flow

1. Message arrives at the router from an inbound business service 2. Router evaluates the message against each routing rule in order 3. For the first matching rule (or all matching rules, depending on configuration), the message is sent to the specified target 4. If no rules match, the message follows the default TargetConfigNames path 5. The target component processes the message (transformation, storage, or further routing)

---

Overview

Each healthcare data format has distinct characteristics that inform how routing rules should be constructed. HL7 v2 messages carry their type information in the MSH segment, x12 transactions identify themselves through interchange and transaction set headers, and CDA documents are categorized by their document type codes and template identifiers. Routing rules must leverage these format-specific properties to correctly direct messages through the processing pipeline.

Well-designed routing rules ensure that each message receives the appropriate transformation and processing based on its format and content.

Creating HL7 Routing Rules

• Access the routing rule editor through Interoperability > Build > Business Rules
• Create rules that evaluate MSH:9 (Message Type) to determine the message category
• Common rule conditions:
• HL7.{MSH:MessageType.MessageCode} = "ADT" for admission/discharge/transfer messages
• HL7.{MSH:MessageType.TriggerEvent} = "A01" for specific trigger events
• HL7.{MSH:SendingFacility} for source-based routing
• Actions: Send to specific transformation DTL, route to processing business process, or discard
• Group related rules into rule sets for organizational clarity

Creating x12 Routing Rules

• x12 routing evaluates the ST segment (Transaction Set Header) for the transaction set identifier
• Route 834 transactions (enrollment) to enrollment-specific processing components
• Route 837P (professional claims) and 837I (institutional claims) to their respective processors
• Condition expressions reference x12 document properties for transaction identification
• Consider routing by ISA segment values for source-specific processing

Creating CDA Routing Rules

• CDA documents are routed based on the document type code in the ClinicalDocument header
• Route Continuity of Care Documents (CCD) differently from Discharge Summaries or Progress Notes
• Evaluate template OIDs to identify specific CDA document profiles
• CDA routing may also consider the document source (CustodianOrganization) for facility-specific processing
• Actions can include CDA-specific transformation DTLs or direct SDA conversion pipelines

Action Types in Routing Rules

• Send: Forward the message to a specified target component
• Transform: Apply a DTL transformation before sending to the target
• Discard: Drop the message without further processing (use for unwanted message types)
• Suspend: Hold the message for manual review or delayed processing
• Return: Send a response back to the upstream component (e.g., for acknowledgments)

---

Overview

Data Transformation Language (DTL) is the primary tool in HealthShare UCR for converting data between formats and versions. DTL transformations define explicit field-by-field mappings between a source message schema and a target schema. The graphical DTL editor in the Management Portal provides a visual interface for creating these mappings, while the underlying DTL code can be edited directly for advanced scenarios.

DTL is used for both format conversion (HL7 to SDA, CDA to SDA) and version conversion (HL7 v2.3 to v2.5.1). Understanding DTL is fundamental to configuring data feeds in UCR.

Graphical DTL Editor

• Access via Interoperability > Build > Data Transformations in the Management Portal
• Select source class/schema (e.g., EnsLib.HL7.Message with schema 2.3:ADT_A01)
• Select target class/schema (e.g., EnsLib.HL7.Message with schema 2.5.1:ADT_A01)
• Left panel displays source message structure; right panel displays target message structure
• Drag fields from source to target to create mappings
• Add functions, conditions, and computed values through the action panel
• Test transformations with sample messages directly in the editor

HL7 Version Transformations

• Converting HL7 v2.3 to v2.5.1 is a common requirement when source systems use older HL7 versions
• Version differences include new segments, restructured fields, and expanded code sets
• Key mapping considerations:
• PID segment: Field positions may shift between versions
• OBX segment: Value type and observation identifier structure differences
• MSH segment: Version identifier and encoding characters
• Use the DTL editor to map version-specific fields and handle structural differences
• Apply default values for target fields that have no source equivalent in the older version

x12 Transformations

• Map x12 segments (ISA, GS, ST, loops) to SDA elements or other target formats
• 834 enrollment data maps to Patient and Coverage SDA containers
• 837 claims data maps to Encounter, Diagnosis, and Procedure streamlets
• Handle x12-specific constructs like hierarchical loops and composite elements
• Use DTL functions for EDI-specific data formatting (date conversion, code translation)

DTL Functions and Features

• String Functions: Concatenate, substring, trim, replace, upper/lower case
• Date Functions: Convert between date formats (HL7 yyyyMMdd to SDA yyyy-MM-dd)
• Lookup Functions: Reference lookup tables for code translation
• Conditional Logic: IF/THEN/ELSE for conditional mapping based on source values
• Iteration: FOR EACH loops for processing repeating segments and groups
• Subtransforms: Call reusable DTL classes from within a parent transformation

---

Overview

HealthShare UCR includes standard HL7-to-SDA transformation logic that handles the most common HL7 message types and segments. Rather than replacing these standard transforms entirely, the supported approach for customization is to use code callback methods that allow custom logic to be inserted at specific points in the standard transformation pipeline. This approach preserves the standard behavior while adding organization-specific processing.

Code callbacks are the recommended customization pattern because they survive HealthShare upgrades. When a new version of HealthShare ships with updated standard transforms, callback-based customizations continue to function because they operate alongside the standard code rather than replacing it.

Callback Method Architecture

• Standard HL7-to-SDA transforms process messages segment by segment
• At defined points during processing, the transform checks for and invokes callback methods
• Callbacks receive the current source segment and target SDA object as parameters
• Custom callback code can modify, enrich, or conditionally alter the transformation result
• Callback methods are implemented in custom subclasses of the standard transform classes

OnBeforeMatch Callback

• Executes before the standard transformation logic processes a segment
• Use cases: pre-validate source data, set default values, modify source data before mapping
• Can access and modify the source segment before standard mapping occurs
• Can set flags or state that the standard logic and OnAfterMatch can reference
• Example: Pre-process a Z-segment to extract custom fields before the standard PID mapping

OnAfterMatch Callback

• Executes after the standard transformation logic has completed for a segment
• Use cases: override mapped values, add additional SDA fields, apply business rules
• Can access both the source segment and the resulting SDA object
• Most commonly used callback for adding custom field mappings
• Example: After standard PID mapping, add a custom patient identifier from a Z-segment to the SDA

Best Practices for Callbacks vs Full DTL Override

• Always prefer callbacks for customizations that augment standard behavior
• Callbacks are maintained separately from standard transforms and survive upgrades
• Full DTL override should only be used when the standard transform is fundamentally incompatible
• If using full override, document thoroughly and plan for re-validation after each upgrade
• Implement callbacks in a custom package namespace (e.g., Custom.HL7.Transforms.*)
• Test callbacks with representative messages covering all relevant segment variations

---

Overview

Clinical Document Architecture (CDA) documents, particularly C-CDA (Consolidated CDA) documents, are a common data format exchanged through IHE profiles and health information exchanges. UCR includes a built-in CDA-to-SDA transformation pipeline that parses CDA XML documents and maps their contents to the SDA data model for storage in the ECR.

Understanding CDA document structure is essential for configuring and troubleshooting CDA data feeds, especially when documents from different sources vary in their use of coded entries, sections, and templates.

CDA Document Structure

• Header: Contains document metadata including patient demographics, author, custodian organization, document type, and effective date
• Body (Structured): Organized into sections, each representing a clinical domain (Problems, Medications, Allergies, Procedures, Results, Vital Signs, Immunizations, etc.)
• Section Narrative: Human-readable text describing the clinical content
• Section Entries: Machine-readable coded data (diagnoses, medications, procedures) using standard terminologies
• Template OIDs: Identify the specific CDA template/profile the document conforms to

CDA-to-SDA Mapping

• CDA header patient information maps to the SDA Patient container
• Each CDA section maps to corresponding SDA streamlet types:
• Problems section maps to Diagnosis streamlets
• Medications section maps to Medication streamlets
• Allergies section maps to Allergy streamlets
• Procedures section maps to Procedure streamlets
• Results section maps to LabOrder/LabResult streamlets
• Vital Signs section maps to Observation streamlets
• Coded entries provide the primary data source for SDA fields
• When coded entries are incomplete, narrative text may be preserved as supplementary information

Handling CDA Sections and Entries

• The transformation pipeline iterates over sections in the CDA body
• For each section, it identifies the section code to determine the SDA target type
• Entries within the section are processed individually, creating separate SDA streamlets
• Entry Act, Observation, Procedure, SubstanceAdministration, and Supply elements are handled
• Nested entries (entryRelationship) are processed recursively to capture supporting information
• Unknown or unsupported sections can be handled by custom extensions to the pipeline

---

Overview

HealthShare UCR supports transforming SDA data and CDA documents into FHIR R4 resources. This capability is essential for supporting modern interoperability requirements, including the CMS Interoperability and Patient Access rules, Payer-to-Payer data exchange, and integration with FHIR-native systems. The transformation pipeline maps SDA streamlets to their corresponding FHIR resource types and packages them into FHIR Bundles for exchange.

The standard SDA-to-FHIR mappings cover the most common clinical data categories and can be extended for organization-specific requirements.

SDA-to-FHIR Resource Mapping

• Patient Container maps to FHIR Patient resource (demographics, identifiers, contacts)
• Encounter Container maps to FHIR Encounter resource (visit details, participants, locations)
• Diagnosis Streamlet maps to FHIR Condition resource (clinical conditions, problems)
• Medication Streamlet maps to FHIR MedicationRequest or MedicationStatement
• Allergy Streamlet maps to FHIR AllergyIntolerance resource
• LabOrder/LabResult Streamlet maps to FHIR DiagnosticReport and Observation resources
• Procedure Streamlet maps to FHIR Procedure resource
• Immunization Streamlet maps to FHIR Immunization resource
• Document Streamlet maps to FHIR DocumentReference resource

FHIR Bundle Creation

• Multiple FHIR resources for a patient are collected into a FHIR Bundle
• Bundle types include searchset (query responses), document (clinical documents), and transaction (batch submissions)
• Each entry in the Bundle contains a FHIR resource with its metadata (resource type, ID, last updated)
• Bundles include references between resources (e.g., Condition references Patient)
• Pagination support for large result sets using Bundle links (next, previous)

CDA-to-FHIR Pipeline

• CDA documents follow a two-stage pipeline: CDA to SDA, then SDA to FHIR
• The intermediate SDA representation allows the same SDA-to-FHIR mappings to apply regardless of original source format
• This pipeline supports converting legacy CDA documents to modern FHIR format
• Template-specific handling ensures that CDA sections map correctly through the SDA intermediate step
• Custom extensions to either stage of the pipeline can accommodate non-standard content

FHIR Profile Conformance

• Generated FHIR resources should conform to required profiles (US Core, Da Vinci, etc.)
• Profile conformance includes required elements, value set bindings, and structural rules
• The standard SDA-to-FHIR mappings target US Core profiles by default
• Custom mappings may be needed to satisfy additional profile requirements
• Validate generated FHIR resources against profiles using the FHIR validation framework

---