T9.3: Post-Installation Configuration

Overview

SSL/TLS configuration is one of the first and most critical post-installation tasks. All communication between UCR components must be encrypted using SSL/TLS, and each component must have properly configured SSL/TLS settings before it can participate in the federation.

Creating SSL/TLS Configurations

SSL/TLS configurations are created in the Management Portal under System Administration > Security > SSL/TLS Configurations. Each configuration includes:

• Configuration name: A descriptive name that will be referenced by business services and operations
• Server or client type: Whether the configuration is for incoming (server) or outgoing (client) connections
• Certificate file: The X.509 certificate for this component
• Private key file: The private key associated with the certificate
• CA certificate file: The certificate authority chain for verifying peer certificates
• Protocols: TLS version support (TLS 1.2 and/or TLS 1.3 recommended)
• Cipher suites: Acceptable encryption algorithms

Certificate Management

Each UCR component typically needs:

• A server certificate for accepting incoming connections
• A client certificate for making outgoing connections to other components
• CA certificates for all certificate authorities in the federation's trust chain

Certificate planning should include:

• Consistent naming conventions for certificates
• A certificate authority (internal CA or commercial CA) for issuing certificates
• Certificate renewal procedures before expiration
• Secure storage of private keys

Configuration Per Component

• Registry: Needs server SSL/TLS for accepting connections from Edge and Access Gateways; needs client SSL/TLS for connecting to the Audit Edge
• Edge Gateway: Needs server SSL/TLS for accepting queries from Access Gateways; needs client SSL/TLS for connecting to the Registry and Audit Edge
• Access Gateway: Needs client SSL/TLS for connecting to Edge Gateways and the Registry
• Bus: Needs both server (for external clients) and client (for internal connections) SSL/TLS
• ODS: Needs server SSL/TLS for FHIR API clients; needs client SSL/TLS for data synchronization

---

Overview

After SSL/TLS is configured, the next step is to establish the communication pathways between UCR components. This involves configuring each component with the network endpoints of the other components it needs to communicate with.

Edge Gateway to Registry Communication

Each Edge Gateway must be configured with:

• The Registry's SOAP endpoint URL for patient registration (PIX)
• The Registry's endpoint for document metadata submission (XDS.b)
• The Registry's endpoint for notification delivery
• SSL/TLS configuration name to use for these connections

Access Gateway to Registry Communication

Each Access Gateway must be configured with:

• The Registry's endpoint for patient search queries (PDQ)
• The Registry's endpoint for patient identity resolution (PIX)
• SSL/TLS configuration name for Registry connections

Access Gateway to Edge Gateway Communication

Access Gateways query Edge Gateways for clinical data. Configuration includes:

• Edge Gateway SOAP endpoints for document retrieval
• The mechanism for discovering which Edge Gateways hold data for a given patient (typically via Registry metadata)
• SSL/TLS configuration for Edge Gateway connections

All Components to Audit Edge Communication

Every component must be configured to send audit events to the Audit Edge:

• Audit Edge endpoint URL
• SSL/TLS configuration for audit connections
• Audit event format and delivery settings

Testing Connectivity

After configuring endpoints:

• Use the Management Portal to test SOAP connections
• Verify SSL/TLS handshakes complete successfully
• Check that firewall rules allow traffic on the configured ports
• Review connection logs for errors or warnings

---

Overview

Pool sizes determine how many concurrent instances of a business host (service, process, or operation) can run simultaneously within a production. Proper pool size configuration is essential for performance, and InterSystems provides recommended settings for each UCR component type.

Understanding Pool Sizes

• A pool size of 1 means only one instance of the business host runs at a time (serial processing)
• A pool size greater than 1 allows parallel processing of messages
• A pool size of 0 disables the business host entirely
• Setting pool sizes too high can exhaust system resources (memory, connections)
• Setting pool sizes too low can create processing bottlenecks

Registry Recommended Pool Sizes

The Registry handles patient identity and metadata operations. Key pool size recommendations include:

• PIX Manager services: Sized based on the number of Edge Gateways submitting patient data
• PDQ services: Sized based on the number of concurrent patient search queries
• XDS.b Registry services: Sized based on document registration volume
• Notification services: Sized based on notification delivery load

Edge Gateway Recommended Pool Sizes

Edge Gateways process incoming clinical data and respond to queries:

• Data intake services: Sized based on the volume and frequency of data feeds from source systems
• ECR storage operations: Sized to match intake throughput
• Query response services: Sized based on expected query load from Access Gateways

Access Gateway Recommended Pool Sizes

Access Gateways handle clinician queries:

• Patient search services: Sized based on concurrent Clinical Viewer users
• Document retrieval operations: Sized based on the number of Edge Gateways being queried in parallel
• CDA transform processes: Sized based on document rendering load

Bus Recommended Pool Sizes

• External-facing services: Sized based on expected third-party query volume
• Internal routing operations: Sized to match external service throughput

ODS Recommended Pool Sizes

• Data synchronization services: Sized based on update frequency and volume
• FHIR server endpoints: Sized based on expected API client load
• Index building processes: May need higher pool sizes during initial data load

---

Overview

After individual component installation and SSL/TLS configuration, each Edge Gateway must be formally registered with the Registry. This registration establishes the gateway as a recognized participant in the federation and enables data exchange.

Registration Process

Edge Gateway registration involves:

• Adding the Edge Gateway as an entry in the Registry's system registry
• Configuring the Edge Gateway's identity (name, OID, endpoint URLs)
• Associating the gateway with one or more healthcare facilities
• Establishing the trust relationship via SSL/TLS certificates
• Verifying bidirectional communication between the gateway and Registry

System Registry Configuration

The system registry in the Hub maintains information about each connected system:

• System name and identifier
• System type (Edge Gateway, Access Gateway, Bus, etc.)
• Endpoint URLs for each supported service
• Associated facility information
• OID assignments for IHE transactions
• Status (active, inactive, maintenance)

Facility Association

During registration, the Edge Gateway is linked to specific facilities:

• The facility identifier is used for consent policy application
• Patient identities submitted from the gateway are tagged with the facility context
• The association determines which data belongs to which facility for consent filtering

Verification Steps

After registration, verify:

• The Edge Gateway appears in the Registry's system registry
• The Edge Gateway can successfully submit a test patient identity to the Registry
• The Registry can route queries to the Edge Gateway
• Audit events from the Edge Gateway reach the Audit Edge

---

Overview

The Master Patient Index (MPI) is one of the most critical components of the UCR Registry. It resolves patient identities across all facilities in the federation, determining when records from different sources refer to the same patient. Proper MPI configuration is essential for data quality and patient safety.

MPI Engine Components

The MPI engine consists of:

• Matching algorithms: Rules that compare patient demographics to determine if two records represent the same person
• Search parameters: Configuration of which demographic fields (name, date of birth, gender, SSN, address, etc.) are used in matching
• Scoring thresholds: Numerical thresholds that determine when a match is considered definitive, possible, or unlikely
• Link management: Rules for automatically linking confirmed matches and flagging potential matches for manual review

Matching Algorithm Configuration

Key configuration decisions include:

• Which matching algorithm to use (probabilistic, deterministic, or hybrid)
• Weighting of different demographic fields in the matching score
• Handling of name variations, nicknames, and transliterations
• Address standardization and comparison methods
• Phone number and identifier comparison rules

Threshold Configuration

Thresholds determine the MPI's behavior when matches are found:

• Auto-link threshold: Score above which matches are automatically confirmed
• Review threshold: Score range where matches are flagged for manual review
• No-match threshold: Score below which records are considered distinct patients
• Setting thresholds too low creates false positives (incorrect links)
• Setting thresholds too high creates false negatives (missed matches)

Duplicate Management

The MPI must handle:

• Automatic linking of high-confidence matches
• Manual review queues for borderline matches
• Unlink capabilities for incorrectly linked records
• Merge operations for confirmed duplicate records
• Notification of linking events to downstream systems

---

Overview

The Audit Edge is a specially designated Edge Gateway that houses the federation's centralized audit repository. During post-installation configuration, the designated Edge Gateway must be configured for its audit role, and all other components must be configured to forward audit events to it.

Configuring the Audit Edge

Configuration of the Audit Edge involves:

• Enabling the audit repository on the designated Edge Gateway
• Creating the audit database with appropriate sizing
• Configuring audit event retention policies
• Setting up the audit service endpoints that other components will connect to
• Verifying that the Audit Edge can receive and store audit events

Configuring Other Components

Every other UCR component must be configured to forward audit events to the Audit Edge:

• Registry: Configure audit forwarding to the Audit Edge endpoint
• Other Edge Gateways: Configure audit event delivery to the Audit Edge
• Access Gateways: Configure audit trail submission for Clinical Viewer access events
• Bus: Configure audit forwarding for external system interactions
• ODS: Configure audit forwarding for data access events

Audit Event Types

The Audit Edge collects events including:

• Patient record access events (who viewed what patient data)
• Clinical data queries and retrievals
• Patient identity operations (searches, links, unlinks)
• Administrative actions (configuration changes, user management)
• Consent policy changes and enforcement events
• System health and error events

Storage and Retention

Audit data management considerations:

• Audit data grows continuously and requires dedicated storage planning
• Retention policies must comply with regulatory requirements (HIPAA requires minimum 6 years)
• Archive and purge procedures should be established
• Audit data must be backed up as part of disaster recovery planning

---

Overview

The System Index is a Registry-hosted feature that provides federation-wide health monitoring. It tracks the status and connectivity of all registered UCR components, enabling administrators to quickly identify and respond to issues.

System Index Functionality

The System Index provides:

• Real-time status monitoring of all registered components
• Connectivity verification between components
• Performance metrics collection
• Alert generation for degraded or failed components
• Historical status tracking for trend analysis

Configuration Steps

Setting up the System Index involves:

• Enabling the System Index feature on the Registry
• Configuring monitoring intervals (how frequently the System Index checks each component)
• Setting up alert thresholds for response time and availability
• Configuring notification channels for alerts (email, SNMP, etc.)
• Registering all components that should be monitored

Monitoring Capabilities

The System Index tracks:

• Connectivity: Whether each component is reachable from the Registry
• Response time: How quickly each component responds to health check queries
• Production status: Whether the production on each component is running
• Queue depths: Message queue depths on business hosts (potential bottleneck indicator)
• Error rates: Frequency of errors on monitored components

Using System Index Data

Administrators can use System Index data to:

• Identify components that are down or degraded before users report issues
• Track performance trends to plan capacity upgrades
• Diagnose intermittent connectivity issues
• Verify that all components are operational after maintenance windows
• Generate reports on federation availability and uptime

---

Overview

UCR components must be started and stopped in a specific order to ensure proper operation. The startup sequence follows the dependency chain: components that provide services to others must be running before the components that consume those services.

Startup Sequence

The correct production startup order is:

1. Registry (Hub): Start first. The Registry provides MPI, consent, and coordination services that all other components depend on. No other component can function properly without the Registry.

2. Audit Edge Gateway: Start second (or alongside other Edge Gateways). The Audit Edge should be available early so that other components can begin forwarding audit events as they start.

3. Edge Gateways: Start after the Registry is confirmed running. Edge Gateways need the Registry to register patient identities and document metadata. They also need the Audit Edge for audit event forwarding.

4. Access Gateways: Start after Edge Gateways are available. Access Gateways query Edge Gateways for clinical data, so starting them before Edge Gateways are running will result in failed queries.

5. Bus: Start after the Registry and Edge Gateways are running, as the Bus needs to query both for external system requests.

6. ODS: Start after Edge Gateways are running, as the ODS synchronizes data from Edge Gateways.

Shutdown Sequence

The shutdown order is the reverse of startup:

1. ODS: Stop first to cease data synchronization 2. Bus: Stop external-facing services 3. Access Gateways: Stop clinician access (notify users of planned downtime) 4. Edge Gateways: Stop data collection (may need to coordinate with source systems) 5. Audit Edge: Stop last among Edge Gateways to capture shutdown audit events 6. Registry: Stop last, after all other components have stopped

Startup Verification

After starting each component, verify:

• The production is running without errors
• Business services and operations are active
• SSL/TLS connections to dependent components succeed
• Test transactions complete successfully
• Audit events are being forwarded to the Audit Edge

Common Startup Issues

• Components failing to connect to the Registry (check Registry is running and endpoints are correct)
• SSL/TLS handshake failures (check certificate validity and trust configuration)
• Pool size errors (check available system resources)
• Stale connections from previous sessions (may need to restart specific business hosts)

---