T1.4: Onboards Data and Configures Data Feeds

Overview

The Edge Gateway serves as the data collection point for each facility contributing data to a HealthShare Unified Care Record federation. Before clinical data can flow into the UCR, the Edge Gateway must be configured with the appropriate inbound services to receive data from each source system at that facility. This involves configuring business services with the correct adapters, connection parameters, and routing targets.

Each source system may use a different transport protocol and message format. A hospital may send HL7 v2 ADT and ORU messages over TCP/MLLP, while a lab system sends results via file drops, and a modern EHR contributes FHIR resources over HTTP. The Edge Gateway must accommodate all of these simultaneously.

Configuring Inbound Business Services

• HL7 TCP Business Service: Uses EnsLib.HL7.Service.TCPService or a HealthShare-specific subclass. Configure the TCP port, IP address binding, MLLP framing characters, character encoding (UTF-8 recommended), and acknowledgment mode (immediate ACK, application ACK, or deferred ACK).
• File Adapter Business Service: Monitors a directory for incoming files. Configure the file path, file specification pattern (e.g., *.hl7), archive path, and polling interval. Suitable for batch processing and systems that produce file-based output.
• HTTP/REST Business Service: Receives data via HTTP POST requests. Configure the endpoint path, port, SSL/TLS certificate, and authentication method. Used for FHIR resources and CDA documents.
• SOAP Business Service: Receives data via SOAP web service calls. Configure the WSDL, endpoint URL, and security settings. Used for IHE profile-based data exchange.

Routing Configuration

• Set TargetConfigNames on each business service to route messages to the appropriate downstream business process
• Multiple targets can be comma-separated for fan-out routing patterns
• A routing business process can further distribute messages based on type, source, or content
• Test routing with sample messages before going live with production data

Best Practices for Feed Setup

• Document each data feed including source system, transport protocol, message types, and expected volume
• Use descriptive naming conventions for business services (e.g., "HospitalA.HL7.ADT.In")
• Configure appropriate timeout and retry settings based on source system characteristics
• Enable error alerting for connection failures and processing errors
• Maintain a feed inventory for the Edge Gateway to track all active data sources

---

Overview

HealthShare UCR ships with a comprehensive set of pre-built data transformations that handle conversion from common healthcare data formats into the SDA (Summary Document Architecture) internal data model. These out-of-the-box transformations cover the most common message types and data elements, reducing the implementation effort required for standard data feeds.

Understanding what is available out of the box is essential for planning an implementation. If source data conforms to standard message structures, the built-in transforms may be sufficient without any customization.

Standard HL7 v2 Transformations

• ADT Messages: Map patient demographics, encounters, insurance, and next-of-kin information from PID, PV1, IN1, NK1, and related segments to SDA Patient and Encounter containers
• ORU Messages: Map observation results from OBR and OBX segments to LabOrder, RadOrder, and other result streamlets
• ORM Messages: Map order information from ORC and OBR segments to order-related SDA streamlets
• SIU Messages: Map scheduling information to Appointment streamlets
• MDM Messages: Map document notification and content to Document streamlets
• Standard Z-Segment Handling: Built-in transforms ignore Z-segments by default; custom DTL is required to process them

When Defaults Are Sufficient

• Source system sends standard HL7 v2 messages following the specification
• No facility-specific Z-segments that carry critical clinical data
• Code values use recognized coding systems (ICD-10, CPT, LOINC, SNOMED)
• Date/time formats follow HL7 standards
• Patient identifiers follow expected patterns and structures

When Custom Transformations Are Needed

• Source system uses non-standard segment ordering or custom Z-segments
• Local code values require translation to federation standards
• Date or time formats deviate from HL7 conventions
• Additional data enrichment is required during transformation
• Business rules need to be applied during the transformation process

---

Overview

Before configuring data feeds, implementers must analyze sample messages from each source system to understand the data formats, content, and quality. This analysis informs the configuration of transformations, identifies customization requirements, and highlights potential data quality issues that need to be addressed before going live.

Thorough analysis of incoming data reduces surprises during implementation and ensures that the configured transformations produce accurate SDA output for the ECR.

Sample Message Analysis Process

1. Request representative samples of each message type from the source system (ADT, ORU, ORM, etc.) 2. Include samples that cover different scenarios (new patient, update, merge, different result types) 3. Open samples in the HL7 message viewer in the Management Portal or a dedicated HL7 analysis tool 4. Document each segment and field present in the messages 5. Compare against the SDA target model to identify standard and non-standard content

Field Mapping Review

• Map each source field to its corresponding SDA target field
• Identify direct mappings (field-to-field copy with no transformation)
• Identify computed mappings (fields requiring format conversion, concatenation, or lookup)
• Flag fields with no SDA target that may require SDA extension or custom containers
• Note repeating segments and groups that require iteration logic in DTL

Identifying Gaps and Custom Requirements

• Missing Identifiers: Source may not include all expected patient identifiers (MRN, SSN, insurance ID)
• Non-Standard Codes: Local codes that need translation to federation standards
• Z-Segments: Custom segments containing facility-specific clinical data
• Custom Fields: Data elements that do not map to any standard SDA property
• Data Quality Issues: Missing required fields, inconsistent formatting, truncated values

---

Overview

After analyzing sample data, implementers must plan the customizations needed to ensure complete and accurate data ingestion. This planning phase translates the findings from data analysis into a concrete implementation plan that includes custom DTL transformations, code callbacks, routing rules, and potentially SDA extensions.

Effective planning ensures that customizations are implemented efficiently, tested thoroughly, and documented for ongoing maintenance.

Custom DTL Creation

• Create new DTL classes for message types or segments not covered by standard transforms
• Extend existing DTL transforms for facility-specific variations
• Design DTL subtransforms for reusable mapping logic (e.g., address parsing, name formatting)
• Use conditional logic in DTL to handle different message variants from the same source
• Plan for iterating over repeating segments and complex data types

Code Callbacks for Standard Transforms

• HealthShare provides supported callback methods (OnBeforeMatch, OnAfterMatch) for customizing standard transforms
• Use callbacks to inject additional logic without replacing the entire standard transform
• Callbacks are preferred over full DTL replacement because they survive upgrades
• Plan which callback points are needed based on the identified customization requirements
• Document the callback logic and its purpose for maintenance

Custom Routing Rules

• Design routing rules to handle messages differently based on type, source, or content
• Create rule sets that evaluate message properties and route to appropriate transformation components
• Plan for future sources by designing flexible routing that can accommodate new data feeds
• Consider using lookup tables for routing criteria that may change over time

---

Overview

Object Identifiers (OIDs) are hierarchical identifiers used throughout the HealthShare UCR federation to ensure unambiguous identification of facilities, identifier-assigning authorities, coding systems, and other entities. Properly configuring OIDs is essential for data consistency because they allow the system to correctly attribute data to its source, match patients across systems, and normalize terminology.

Without correct OID configuration, data from different facilities may be misattributed, patient matching may fail, and terminology translation cannot function correctly.

Facility OIDs

• Each facility contributing data to the federation must have a unique OID
• Facility OIDs are registered in the Facility Registry
• They identify the source of clinical data in messages and SDA containers
• Used in IHE transactions to identify document sources and repositories
• Must be coordinated across the federation to prevent duplication

Assigning Authority OIDs

• Identify the system that assigns patient identifiers (e.g., the MRN system at each hospital)
• Essential for patient matching and identity management
• Registered in the Assigning Authority Registry
• Each identifier domain (MRN, account number, insurance ID) should have a distinct assigning authority OID
• Used by the EMPI to track which system assigned which patient identifier

Code System OIDs

• Identify standard coding systems used in clinical data (ICD-10, CPT, LOINC, SNOMED CT, RxNorm)
• Used in terminology translation to identify source and target code systems
• Registered in the OID Registry for reference by translation profiles
• Ensure that codes are correctly interpreted regardless of which facility sent the data
• Critical for clinical decision support, reporting, and data aggregation across facilities

Configuration Steps

1. Obtain or generate OIDs for each facility, assigning authority, and code system 2. Register facility OIDs in the Facility Registry 3. Register assigning authority OIDs in the Assigning Authority Registry 4. Register code system OIDs in the OID Registry 5. Configure Edge Gateway components to reference the correct OIDs for their facility 6. Verify OID consistency across Edge Gateways and the Hub Registry

---

Overview

The Service Registry is a central catalog within HealthShare UCR that maintains information about all integration services and endpoints in the federation. It serves as the single source of truth for how components communicate with each other and with external systems. When a business host needs to send data to another component or system, it can look up the target endpoint in the Service Registry rather than having hard-coded connection details.

Proper Service Registry management ensures that integration endpoints are documented, discoverable, and maintainable across the federation.

What the Service Registry Contains

• Service Name: A descriptive name for the service (e.g., "HospitalA-EdgeGateway-HL7")
• Endpoint URL: The network address and port for reaching the service
• Protocol Type: The communication protocol (TCP, HTTP, HTTPS, SOAP)
• Service Type: The category of service (Edge Gateway, Hub, IHE Repository, FHIR Server)
• Status: Whether the service is active, inactive, or in maintenance
• Configuration Parameters: Additional settings specific to the service type

Adding and Editing Entries

• Navigate to the Service Registry in the HealthShare Management Portal
• Create new entries by providing the service name, endpoint, protocol, and type
• Edit existing entries when endpoints change (IP address migration, port changes, SSL certificate updates)
• Deactivate entries for services that are temporarily or permanently offline
• Maintain version history of changes for audit and troubleshooting purposes

Endpoint Registration

• Register each Edge Gateway's inbound and outbound endpoints
• Register Hub Registry services for Edge Gateway communication
• Register IHE endpoints for cross-community document sharing
• Register FHIR server endpoints for modern API-based integrations
• Include authentication requirements and credential references for secured endpoints

Service Discovery

• Production components can query the Service Registry at runtime to resolve endpoint addresses
• This decouples service location from production configuration
• Enables dynamic failover if primary endpoints become unavailable
• Supports environment-specific configurations (development, test, production) through registry entries
• Reduces the need to update production settings when service endpoints change

---

Overview

HealthShare UCR provides a rich set of prebuilt adapters that handle the most common transport protocols and message formats used in healthcare integration. These adapters encapsulate the complexity of connection management, protocol handling, and error recovery, allowing implementers to focus on business logic rather than low-level communication details.

When prebuilt adapters do not meet specific requirements, custom business components can be created by extending the appropriate base classes. This approach preserves the adapter pattern while adding organization-specific logic.

Available Prebuilt Adapters

• HL7 TCP Adapter (EnsLib.HL7.Adapter.TCPInboundAdapter / TCPOutboundAdapter): Handles TCP/MLLP connections for HL7 v2 messaging. Supports configurable ports, character encoding, MLLP framing, acknowledgment modes, and connection pooling. Most commonly used adapter for hospital system integration.
• File Adapter (EnsLib.File.InboundAdapter / OutboundAdapter): Monitors directories for incoming files and writes output files. Supports file specification patterns, archive paths, polling intervals, and file locking. Used for batch processing, file drops, and systems that produce file-based output.
• HTTP Adapter (EnsLib.HTTP.InboundAdapter / OutboundAdapter): Handles HTTP/HTTPS communication for REST APIs and web-based integrations. Supports SSL/TLS, authentication (Basic, OAuth2, API keys), custom headers, and content type configuration. Used for FHIR endpoints and CDA document exchange.
• SOAP Adapter (EnsLib.SOAP.InboundAdapter / OutboundAdapter): Handles SOAP web service communication. Supports WSDL-based service definition, WS-Security, SSL/TLS, and SOAP envelope management. Used for IHE profile-based integrations (XDS.b, PDQ, PIX).

Creating Custom Business Services

• Extend Ens.BusinessService or a HealthShare-specific base class
• Override the OnProcessInput method to implement custom message reception logic
• Associate an appropriate adapter for transport-level communication
• Register the custom class in the Edge Gateway production
• Configure adapter settings and TargetConfigNames for downstream routing
• Custom services are useful for proprietary protocols, custom file formats, or complex reception logic

Creating Custom Business Operations

• Extend Ens.BusinessOperation or a HealthShare-specific base class
• Implement message handler methods for each message type the operation should process
• Associate an appropriate adapter for outbound communication
• Register the custom class in the production and configure as a routing target
• Custom operations are useful for writing to external databases, calling proprietary APIs, or generating custom output formats

Creating Custom Business Processes

• Extend Ens.BusinessProcess or use BPL (Business Process Language) for visual orchestration
• Implement complex routing, orchestration, or multi-step processing logic
• Can coordinate multiple downstream operations and aggregate results
• BPL provides a visual designer for workflow-based processes
• Custom processes are useful when standard routing rules are insufficient for the business logic

Best Practices

• Prefer prebuilt adapters when they meet requirements; create custom components only when necessary
• Separate transport concerns (handled by adapters) from business logic (handled by components)
• Follow HealthShare coding conventions and use supported extension points
• Implement comprehensive error handling and logging in custom components
• Test custom components with representative data before deploying to production
• Document custom components including their purpose, configuration, and dependencies

---