T2.2: Extends SDA for Custom Data Elements

Overview

HealthShare UCR provides a rich set of extension points and customization mechanisms that allow implementers to adapt the system to organization-specific requirements. However, following the correct customization patterns is critical for maintaining system stability, ensuring upgradeability, and receiving InterSystems support. The fundamental rule is to never modify system-provided classes directly; instead, use the supported extension mechanisms including subclassing, code callbacks, and custom package namespaces.

Deviating from supported customization patterns can result in lost customizations during upgrades, unsupported system states, and difficulty obtaining technical support from InterSystems.

Supported Customization Patterns

• Subclassing: Create custom subclasses that extend system-provided classes. Override specific methods to add custom behavior while inheriting standard functionality. This is the primary customization mechanism for SDA, transforms, and business components.
• Code Callbacks: Use the supported callback methods provided by HealthShare for injecting custom logic into standard processing pipelines. Callbacks are invoked by the standard code at defined points and do not require modifying the standard classes.
• Custom DTL Transforms: Create new DTL transformation classes for custom data mapping requirements. Reference custom DTLs in production configuration rather than modifying standard DTLs.
• Configuration-Based Customization: Use production settings, lookup tables, and registry entries to alter system behavior without code changes.
• Custom Business Components: Create custom business services, processes, and operations by extending the appropriate base classes.

Unsupported Customization Patterns

• Direct Editing of HS.* Classes: Never modify classes in the HS, HSMOD, HSAA, HSCV, or other system namespaces. These classes are overwritten during upgrades.
• Modifying Standard DTLs: Do not edit the built-in DTL transformations. Create custom DTLs or use callbacks instead.
• Patching Compiled Code: Do not modify .INT or .OBJ code directly. Always work with source classes.
• Modifying System Globals: Do not directly edit system globals that store configuration or data managed by HealthShare classes.

Custom Package Namespace Convention

• Use a dedicated package prefix for all custom classes (e.g., Custom.UCR.*, Site.HS.*, Org.*)
• Organize custom classes by functional area (Custom.UCR.Transforms.*, Custom.UCR.SDA.*, Custom.UCR.Components.*)
• Maintain clear naming that indicates the purpose of each custom class
• Document the relationship between custom classes and the system classes they extend
• This organization makes custom code easy to identify, deploy, and maintain across environments

---

Overview

The Summary Document Architecture (SDA) is the canonical internal data model used throughout HealthShare UCR. All clinical data flowing through the system, regardless of its original format (HL7, CDA, FHIR, x12), is converted into SDA format for storage, aggregation, and retrieval. Understanding the SDA data model is essential for implementing data feeds, extending the model for custom data elements, and troubleshooting data flow issues.

SDA serves as the lingua franca of the UCR federation, enabling data from heterogeneous source systems to be stored, searched, and displayed in a unified manner.

SDA Data Model Structure

• Patient Container: The root container for all patient-related data. Contains demographics, identifiers, addresses, phone numbers, and relationships to other containers.
• Encounter Container: Represents a clinical encounter (visit, admission, appointment). Contains encounter type, dates, providers, facility, and links to clinical streamlets.
• Streamlets: Individual clinical data elements that represent specific types of clinical information:
• Diagnosis: Clinical diagnoses and problem list entries
• Medication: Prescribed and administered medications
• Allergy: Allergies and adverse reactions
• LabOrder / LabResult: Laboratory orders and their results
• RadOrder / RadResult: Radiology orders and results
• Procedure: Clinical and surgical procedures
• Immunization: Vaccination records
• Document: Clinical documents and notes
• Observation: Vital signs and clinical observations

SDA XML Format

• SDA data is exchanged between components as XML documents
• The root element is <Container> with child elements for each data category
• Each streamlet type has a defined XML schema with required and optional elements
• The SDA XML schema defines data types, cardinalities, and allowed values
• Tools in the Management Portal can display SDA XML for debugging and validation

ECR Storage Model

• The Edge Cache Repository (ECR) stores SDA data as streamlets in a persistent database
• Each streamlet is stored as a separate object with metadata (source, timestamp, version)
• Streamlets from multiple sources for the same patient are aggregated in the ECR
• The Hub aggregates streamlets from all Edge Gateways to provide a federated view
• Streamlet versioning tracks changes and allows historical data review

---

Overview

When source systems contain data elements that do not map to any standard SDA property, the SDA model can be extended through extension classes. Extension classes are custom subclasses of standard SDA classes that add new properties (fields) to represent organization-specific data elements. This approach preserves the standard SDA structure while accommodating custom data requirements.

Extending SDA via extension classes is the recommended approach when a data element logically belongs to an existing SDA object but is not represented in the standard schema. For data that does not fit into any existing SDA category, custom containers and streamlets should be considered instead.

Creating Extension Classes

1. Identify the standard SDA class that needs to be extended (e.g., HS.SDA3.Medication) 2. Create a new class in your custom package that extends the standard class (e.g., Custom.SDA3.Medication extends HS.SDA3.Medication) 3. Add new properties to the custom class with appropriate data types and descriptions 4. Compile the custom class and verify that it inherits all standard properties 5. Register the extension class in the HealthShare configuration so the system uses it instead of the standard class

Adding Custom Properties

• Define properties using standard InterSystems IRIS data types (%String, %Integer, %Date, %Boolean, etc.)
• Use property parameters to control storage, indexing, and validation
• Name properties descriptively using the custom namespace convention (e.g., CustomPatientCategory, SiteSpecificCode)
• Add XML projection parameters so custom properties are included in SDA XML serialization
• Properties can be simple values, references to other objects, or collections (lists, arrays)

Mapping Custom Fields from Source Data

• Create or modify DTL transformations to populate custom SDA properties from source messages
• For HL7 sources, map Z-segment fields or non-standard uses of standard fields to custom properties
• For CDA sources, map custom extensions or additional section data to custom properties
• Use code callbacks (OnAfterMatch) to populate custom properties during standard HL7-to-SDA transformation
• Test mappings with sample data to verify that custom properties are correctly populated

Storage and Retrieval

• Extended SDA objects are stored in the ECR with both standard and custom properties
• Custom properties are persisted alongside standard data in the same streamlet storage
• Queries and reports can access custom properties through the standard SDA API
• The Hub aggregates extended SDA data from Edge Gateways, preserving custom properties
• Custom properties are available for display in the Clinical Viewer through UI configuration

---

Overview

While SDA extension classes add properties to existing SDA objects, there are scenarios where the data being captured does not fit into any existing SDA category. In these cases, entirely new SDA containers or streamlets can be created. Custom containers define new top-level data groupings, while custom streamlets define new types of clinical data elements. Creating custom SDA types is a more significant undertaking than extending existing types, requiring configuration across the transformation, storage, and display layers.

Custom SDA types should only be created when the data genuinely represents a new clinical concept that has no home in the standard SDA model.

When to Create New vs Extend Existing

• Extend Existing: When the data logically belongs to an existing SDA type but adds additional attributes (e.g., adding a custom severity score to the Diagnosis streamlet)
• Create New Container: When the data represents a top-level concept with its own lifecycle and relationships (e.g., a custom Research Study container for clinical trial data)
• Create New Streamlet: When the data represents a new type of clinical observation or event that does not fit any existing streamlet (e.g., a custom Social Determinant streamlet for SDOH data)
• Consider whether the data will be sourced, aggregated, and displayed independently from existing types

Creating Custom Container Classes

1. Define a new class that extends the appropriate SDA base container class 2. Add properties that represent the container's data elements 3. Define the XML projection for SDA XML serialization and deserialization 4. Register the custom container in the HealthShare type registry 5. Create DTL transformations that produce instances of the custom container from source data 6. Configure ECR storage to persist the custom container 7. Optionally configure Clinical Viewer display for the custom container

Creating Custom Streamlet Classes

1. Define a new class that extends the appropriate SDA streamlet base class (HS.SDA3.AbstractOrder, HS.SDA3.SuperClass, or another appropriate base) 2. Add properties for the streamlet's clinical data elements 3. Define the streamlet's unique identification criteria (which fields constitute a unique instance) 4. Register the custom streamlet type with the HealthShare streamlet registry 5. Configure the aggregation logic for how multiple instances from different sources are merged 6. Create DTL transformations to produce instances of the custom streamlet 7. Configure the Clinical Viewer to display custom streamlet data

Registration and Configuration

• Custom SDA types must be registered in the system configuration for the ECR, Hub, and Clinical Viewer to recognize them
• Registration involves mapping the custom type to its storage class, aggregation rules, and display configuration
• Without registration, custom SDA data will not be stored, aggregated, or displayed correctly
• Test the complete pipeline from data ingestion through transformation, storage, aggregation, and display
• Document custom SDA types including their purpose, schema, sources, and display configuration

---

Overview

Patient matching is a critical function in HealthShare UCR that determines whether records from different source systems belong to the same patient. The EMPI (Enterprise Master Patient Index) uses matching algorithms to compare patient demographics and identifiers across records and assign match scores. Customizing the matching logic allows organizations to tune matching behavior for their specific patient population, data quality characteristics, and business rules.

Matching customization ranges from simple threshold adjustments to implementing entirely custom matching algorithms. The appropriate level of customization depends on the matching accuracy requirements and the characteristics of the patient data.

Patient Matching Architecture

• When new patient data arrives at the Edge Gateway, it is evaluated against existing patient records
• The EMPI compares patient demographics (name, date of birth, gender, address) and identifiers (MRN, SSN, insurance ID)
• Each comparison produces a match score based on the degree of agreement between fields
• The score is compared against thresholds to determine the match outcome:
• Match: Score exceeds the match threshold; records are automatically linked
• Possible Match: Score falls between match and no-match thresholds; requires manual review
• No Match: Score falls below the no-match threshold; a new patient record is created
• Match results are stored and can be reviewed and overridden by authorized users

Matching Algorithms

• Deterministic Matching: Exact comparison of specific fields (e.g., exact MRN match within the same assigning authority)
• Probabilistic Matching: Statistical comparison using multiple weighted fields to produce a composite score
• Phonetic Matching: Uses algorithms like Soundex or Metaphone for name matching that accounts for spelling variations
• Edit Distance: Measures the number of character changes needed to transform one value into another, useful for catching typos
• Frequency-Based Weighting: Common values (e.g., "Smith") receive less weight than rare values in matching scores

Customizing Match Criteria

• Add additional fields to the matching comparison (e.g., mother's maiden name, phone number, email)
• Adjust the weight assigned to each field in the composite match score
• Configure field-level comparison methods (exact, phonetic, edit distance, substring)
• Define blocking criteria that determine which records are compared (e.g., only compare records with the same first letter of last name and same birth year)
• Blocking criteria reduce the number of comparisons needed, improving performance for large patient populations

Threshold Configuration

• Match Threshold: The score above which records are automatically linked (e.g., 95%)
• Possible Match Threshold: The score above which records are flagged for manual review (e.g., 75%)
• No-Match Threshold: The score below which records are considered distinct patients
• Threshold values should be tuned based on the organization's tolerance for false positives (linking different patients) vs. false negatives (creating duplicate records)
• Start with conservative thresholds and adjust based on match review statistics

Custom Match Code

• Implement custom matching logic by creating classes that extend the standard matching framework
• Custom match code can implement organization-specific rules such as:
• Facility-specific identifier matching (e.g., always link if MRNs match within the same facility)
• Business rule-based matching (e.g., special handling for newborn records)
• Integration with external identity verification services
• Custom match code follows the same subclassing pattern as other HealthShare customizations
• Place custom matching classes in the custom package namespace
• Test custom matching thoroughly with representative patient data, including edge cases

Best Practices for Matching Customization

• Analyze the current matching accuracy before making changes to establish a baseline
• Make incremental changes and measure the impact on match rates and false positive/negative rates
• Maintain a test dataset of known matches and non-matches for regression testing
• Document all matching customizations and the rationale for each change
• Review matching statistics regularly and adjust configurations as data quality improves
• Involve clinical stakeholders in matching threshold decisions, as the consequences of incorrect matching are clinical

---