T11.2: Extends SDA

Overview

Summary Document Architecture (SDA) is the internal clinical data format used throughout the UCR federation. Regardless of the format in which data arrives at the Edge Gateway (HL7 v2, CDA, FHIR, X12), it is transformed into SDA before being stored in the Edge Cache Repository (ECR). When data is retrieved for display in the Clinical Viewer or for sharing with other systems, it is read from the ECR in SDA format and then transformed to the appropriate output format.

SDA serves as the canonical data model that decouples the data ingestion layer from the storage and presentation layers. This architecture means that adding support for a new source format only requires creating new inbound transformations to SDA, without changing the storage or display components.

SDA Data Flow

1. Ingestion: Source data arrives at the Edge Gateway in its native format 2. Transformation: DTL transforms convert the source data to SDA XML 3. Normalization: Terminology translation normalizes codes during or after transformation 4. Storage: SDA is stored in the Edge Cache Repository as containers and streamlets 5. Retrieval: When data is requested, SDA is read from the ECR 6. Presentation: SDA is transformed for display in the Clinical Viewer or export to other formats

SDA XML Structure

• SDA documents are XML with a defined schema
• The root element contains patient identification and metadata
• Clinical data is organized into containers that hold related information
• Each clinical data item is represented as a streamlet within a container
• SDA supports both coded values (with coding system, code, and description) and free-text values

---

Overview

SDA organizes clinical data into a hierarchy of containers and streamlets. Containers represent broad categories of patient data, while streamlets represent individual clinical data items within those categories. Understanding the standard container and streamlet types is essential for configuring data feeds, creating transformations, and extending SDA with custom types.

The standard SDA types cover the vast majority of clinical data needs. However, organizations can extend SDA with custom containers and streamlets when the standard types do not accommodate their specific data requirements.

Standard Containers

• Patient: Patient demographics, identifiers, addresses, phone numbers, insurance, next of kin
• Encounter: Visit and admission data including type, dates, providers, location, disposition
• Clinical Containers: Group related streamlet types for organization and processing

Standard Streamlet Types

• Allergy: Allergy and adverse reaction information (allergen, reaction, severity, status)
• Medication: Medication orders and administration (drug, dose, route, frequency, prescriber)
• Diagnosis: Clinical diagnoses (code, description, onset date, status, diagnosing clinician)
• LabOrder: Laboratory orders and results (test, specimen, result values, reference ranges, status)
• RadOrder: Radiology orders and results (procedure, findings, impression, status)
• Procedure: Surgical and clinical procedures (procedure code, date, provider, outcome)
• Immunization: Vaccination records (vaccine, date, dose, manufacturer, lot number)
• Document: Clinical documents (type, author, date, content as text or encoded binary)
• Problem: Problem list items (code, description, onset, status)
• CarePlan: Care plans and goals
• Alert: Clinical alerts and flags
• FamilyHistory: Family medical history

Streamlet Properties

• Each streamlet type has defined properties matching its clinical purpose
• Common properties include codes (with coding system), dates, status, and provider references
• Streamlets reference the Encounter container for visit context
• Coded values include CodeSystem, Code, and Description fields

---

Overview

SDA extension classes allow organizations to add custom properties to existing SDA streamlet types. Rather than modifying the standard SDA classes (which would be overwritten during upgrades), extensions create subclasses that inherit all standard properties and add new ones. This approach maintains compatibility with the standard UCR pipeline while accommodating organization-specific data requirements.

Extension classes are the recommended approach when the standard SDA types capture the right clinical concept but lack specific properties needed by the organization. For example, extending the Medication streamlet to include a custom formulary status field.

Creating Extension Classes

1. Identify the standard SDA class to extend (e.g., HS.SDA3.Medication) 2. Create a new class that extends the standard class 3. Add custom properties with appropriate data types 4. Define XML projections for the custom properties so they appear in SDA XML 5. Compile the class and update the ECR schema 6. Modify DTL transformations to populate the custom properties 7. Configure the Clinical Viewer to display the custom properties if needed

Extension Class Structure

• The extension class resides in a custom package (e.g., Custom.SDA3.Medication)
• Properties use standard InterSystems data types (String, Date, Integer, etc.)
• XML projection parameters control how properties appear in SDA XML
• Properties can be required or optional
• Validation logic can be added using property validation methods

Considerations

• Extension classes must be registered so the ECR recognizes them
• Existing data in the ECR is not affected by adding extensions (new properties are null for existing records)
• DTL transformations must be updated to populate custom properties for new data
• Clinical Viewer display configuration must be updated to show custom properties
• Extensions survive system upgrades as long as they are in custom packages

---

Overview

Custom SDA containers are needed when an organization has data categories that do not fit into any standard SDA container. While custom streamlets add new data types within existing categories, custom containers create entirely new categories. This is appropriate for data domains that are fundamentally different from standard clinical categories, such as social determinants of health assessments, research protocol data, or specialized care program information.

Creating custom containers is a more significant change than extending existing types and requires careful planning to ensure proper integration with the full UCR pipeline.

When to Create Custom Containers

• The data does not logically fit within any existing SDA container
• The data represents a distinct domain (e.g., social services, research, quality measures)
• The data has unique relationships and properties that differ from standard clinical data
• Existing container extensions would be semantically inappropriate

Defining Custom Containers

1. Create a container class in a custom package 2. Define container-level properties (metadata, identifiers) 3. Define relationships to streamlet types that belong in this container 4. Register the container with the SDA schema 5. Update ECR storage definitions to accommodate the new container 6. Create DTL transformations to populate the container from source data 7. Configure Clinical Viewer display for the container's data

Integration Requirements

• The Edge Gateway pipeline must recognize and process the custom container
• DTL transformations must map source data to the custom container structure
• The ECR must have appropriate storage tables for the container's streamlets
• The Clinical Viewer must be configured to display data from the custom container
• Hub notifications must include information about custom container data availability

---

Overview

Custom streamlet types are created when the standard SDA streamlet types do not cover a specific type of clinical data that the organization needs to capture and display. Unlike extension classes (which add properties to existing types), custom streamlets define entirely new data types with their own property sets. Custom streamlets can be placed within standard or custom containers.

Custom streamlet creation requires defining the data model, registering it with the system, and configuring all pipeline components to handle the new type.

Creating Custom Streamlet Types

1. Identify the data requirements for the custom streamlet (properties, coded values, relationships) 2. Create a new class extending the SDA streamlet base class 3. Define properties with appropriate data types and XML projections 4. Include standard streamlet properties (EnteredBy, EnteredOn, ExternalId, etc.) 5. Register the custom streamlet type with the ECR 6. Create DTL transformations to map source data to the custom streamlet 7. Configure Clinical Viewer profiles to display the custom streamlet

Custom Streamlet Class Structure

• Extends the appropriate SDA base class
• Defines clinical properties (codes, dates, values, text fields)
• Includes coded value properties using the CodeTableDetail type for terminology
• Defines XML element names and projections
• May include relationships to other streamlets or containers

Registration and Configuration

• Register the custom streamlet type in the ECR class definitions
• Update the ECR storage schema to include tables for the custom streamlet
• Configure the pipeline to recognize and process the custom streamlet type
• Create or update translation profiles if the custom streamlet includes coded values
• Add display configuration in the Clinical Viewer (chart items, profiles, layouts)

---

Overview

Once SDA extensions (custom properties, containers, or streamlets) are defined, DTL transformations must be created or updated to populate them from source data. Each source format has its own mechanisms for carrying non-standard data: HL7 v2 uses Z-segments and custom fields, CDA uses template extensions, and FHIR uses extension elements. The source-to-SDA mapping process involves identifying where the custom data resides in each source format and creating appropriate DTL logic to extract and transform it.

Accurate source-to-SDA mapping is critical for ensuring that custom data is properly captured, stored, and available for display in the Clinical Viewer.

Mapping from HL7 v2

• Custom data often resides in Z-segments (e.g., ZPI, ZPD, ZRX)
• Standard segments may carry custom data in unused fields or components
• DTL accesses Z-segment fields using the same segment/field/component notation as standard segments
• Map Z-segment fields to the corresponding custom SDA properties
• Handle repeating Z-segments by iterating in the DTL

Mapping from CDA

• Custom data may be in CDA template extensions or observation sections
• DTL navigates the CDA XML structure to locate custom elements
• XPath-like access patterns extract values from the CDA document
• Map extracted values to custom SDA properties

Mapping from FHIR

• FHIR resources carry custom data in extension elements
• Extensions have a URL identifier and a value of a specific type
• DTL accesses extensions by iterating over the extension array and matching URLs
• Map extension values to custom SDA properties

Testing Source-to-SDA Mappings

• Use the DTL testing tool with sample messages from each source system
• Verify that custom properties are populated correctly in the output SDA
• Test with edge cases: missing custom data, multiple values, coded values
• Validate that the resulting SDA stores correctly in the ECR
• Verify display in the Clinical Viewer

---

Overview

SDA extensions have a direct impact on the Edge Cache Repository, which is the persistent storage layer for clinical data at each Edge Gateway. When custom containers, streamlets, or extension properties are added to the SDA model, corresponding changes must be made to the ECR to store, index, and retrieve the custom data. Understanding the ECR impact is essential for planning and implementing SDA extensions.

The ECR uses InterSystems IRIS persistent classes to store SDA data. Custom SDA types correspond to new persistent classes or properties in the ECR, and the ECR schema must be updated to accommodate them.

Schema Updates

• Custom streamlet types require new persistent storage classes in the ECR
• Extension properties on existing streamlets require new columns in existing storage classes
• Custom containers require new storage class hierarchies
• Schema changes should be applied in a controlled manner (development → test → production)
• Use class compilation and schema migration tools to apply changes

Indexing Considerations

• Properties used in search queries should be indexed for performance
• Standard indices are defined on the ECR storage classes
• Add custom indices for custom properties that will be queried or filtered
• Balance index coverage against storage overhead and insert performance
• Consider bitmap indices for properties with low cardinality (e.g., status fields)

Retrieval and Display

• Custom data must be retrievable through the standard ECR query mechanisms
• The Clinical Viewer data retrieval layer must recognize custom types
• Custom streamlets need display profile configuration in the Clinical Viewer
• Export operations must include custom data when generating SDA, CDA, or FHIR output
• API access to custom data may require additional configuration

Upgrade Management

• Keep custom ECR classes in custom packages separate from system packages
• Document all custom schema changes for upgrade planning
• Test system upgrades in a staging environment with custom schema
• Custom classes in custom packages typically survive upgrades without modification
• Verify custom data integrity after system upgrades

---