T1.2: Installs Software and UCR Components

Overview

Every UCR component runs on the InterSystems IRIS for Health platform. The very first step in any UCR deployment is installing IRIS for Health on each server that will host a component. This installation provides the runtime engine, database server, web server, and management tools that UCR builds upon.

Obtaining the Installation Kit

InterSystems provides installation kits through the WRC (Worldwide Response Center) portal. The deployment specialist must:

• Log in to the WRC at wrc.intersystems.com
• Download the correct version of IRIS for Health that matches the UCR version being deployed
• Select the correct platform kit (Linux x86-64, Windows x86-64, etc.)
• Verify the download integrity using the provided checksums

Installation on Linux

The Linux installation process follows these steps:

• Extract the installation archive to a temporary directory
• Run the irisinstall script as root or with sudo privileges
• Specify the installation directory (e.g., /usr/irissys)
• Specify the instance name (choose a meaningful name reflecting the component type)
• Select the installation type: Server (for production) or Development
• Configure the initial security level: LockedDown (production) or Normal (development)
• Set passwords for the predefined user accounts
• Choose whether to install the built-in Apache web server or use an external web server
• Complete the installation and verify the instance starts successfully

Installation on Windows

The Windows installation uses a GUI installer:

• Run the setup.exe as an Administrator
• Follow the installation wizard through the same decisions (directory, instance name, security level, passwords)
• Choose the service account under which the IRIS instance will run
• Configure the web server integration (IIS or built-in Apache)
• Complete the installation and verify the instance appears in the Windows Services console

Applying the License Key

The license key can be applied through multiple methods:

• During installation: Some installation workflows prompt for the license key file
• Management Portal: Navigate to System Administration > Licensing > License Key and upload the key file
• File copy: Place the iris.key file in the instance's mgr/ directory and restart the instance
• Terminal: Use the %SYSTEM.License class methods from the Terminal to load a key programmatically

After applying the key, verify the license is active by checking System Administration > Licensing > License Usage in the Management Portal.

Post-Installation Verification

After installation, verify:

• The IRIS for Health instance is running (check system services or process list)
• The Management Portal is accessible at the expected URL (e.g., https://server:52773/csp/sys/UtilHome.csp)
• The instance name and version are correct
• The license key is active and shows the expected capacity
• Basic connectivity to the server is confirmed from other servers in the federation

---

Overview

The Web Gateway is the component that connects an external web server (Apache HTTP Server or Microsoft IIS) to the InterSystems IRIS for Health instance. In production UCR deployments, an external web server is used instead of the built-in IRIS private web server. The Web Gateway handles routing web requests from clinicians and administrators to the correct IRIS for Health instance and namespace.

Why Use an External Web Server

Production UCR deployments use an external web server for security (isolating IRIS from direct exposure), performance (optimized static content serving), SSL/TLS termination, load balancing across multiple instances, and compliance with organizational security standards.

Web Gateway Architecture

The Web Gateway consists of a shared library module (CSPa.so on Linux, CSPms.dll on Windows) loaded by the web server, configuration files defining URL-to-instance routing, and the Web Gateway Management page for browser-based configuration.

Apache Configuration on Linux

To configure Apache with the Web Gateway:

• Install Apache HTTP Server if not already present
• Copy the CSP gateway shared library (CSPa24.so or similar) to the Apache modules directory
• Edit httpd.conf to load the CSP module and define the CSP application mappings
• Configure the CSPFileTypes directive to specify which file extensions are handled by IRIS
• Set the Ip-Address and TCP-Port parameters to point to the IRIS for Health SuperServer
• Restart Apache and verify connectivity through the Web Gateway Management page

IIS Configuration on Windows

To configure IIS with the Web Gateway:

• Install the ISAPI filter (CSPms.dll) through the IIS Manager
• Create virtual directories for CSP applications
• Configure application pool settings for the ISAPI filter
• Set the server mapping to point to the IRIS for Health instance
• Verify connectivity through the Web Gateway Management page

Reverse Proxy Setup

Some deployments place a reverse proxy (such as nginx or HAProxy) in front of the web server. The reverse proxy handles external client connections and SSL/TLS termination, forwards requests to the internal Apache or IIS server running the Web Gateway, and can provide load balancing across multiple web server instances.

---

Overview

In a federated UCR deployment, multiple IRIS for Health instances serve different components, and the web server layer must route requests correctly. The deployment specialist must configure the web server infrastructure so that each component's web applications are accessible at the correct URL while maintaining security boundaries between components.

Multi-Instance Routing

In a distributed production deployment, each UCR component runs on a separate IRIS for Health instance. The Web Gateway configuration must map URL paths to the correct instance:

• /csp/healthshare/hub/ routes to the Registry instance
• /csp/healthshare/edge_facility1/ routes to the Edge Gateway for Facility 1
• /csp/healthshare/edge_facility2/ routes to the Edge Gateway for Facility 2
• /csp/healthshare/access/ routes to the Access Gateway instance
• /csp/healthshare/bus/ routes to the Bus instance (if deployed)

Each mapping specifies the target instance's IP address and SuperServer port in the Web Gateway configuration.

Virtual Host Configuration

For production deployments, virtual hosts provide cleaner URL structures and better security isolation:

• Apache: Define separate <VirtualHost> blocks in httpd.conf for each component or component group
• IIS: Create separate IIS sites or applications for each component
• Each virtual host can have its own SSL/TLS certificate, access controls, and logging configuration
• Virtual hosts enable different authentication requirements for different components (e.g., Clinical Viewer vs Management Portal)

Load Balancing for Access Gateways

When multiple Access Gateways are deployed, a load balancer distributes Clinical Viewer traffic across instances. Session affinity (sticky sessions) may be required to maintain user session state. Health checks detect and remove unhealthy nodes from the pool.

Single-Instance Configuration for Development

In a development environment where all components share a single IRIS instance, all web applications are served by the same web server. URL paths differentiate between namespaces (e.g., /csp/healthshare/hub/, /csp/healthshare/edge1/). This simplifies development but does not test the multi-instance routing that exists in production.

Web Application Security

Regardless of topology, the Management Portal should be accessible only from trusted administrative networks, Clinical Viewer access restricted to authorized clinical networks, and SOAP web service endpoints accessible only between components. CSP session security settings should enforce HTTPS-only cookies and appropriate timeouts.

---

Overview

The Installer Wizard is the primary graphical tool for deploying UCR components. It is accessed through the Management Portal and provides a step-by-step interface for creating namespaces, configuring databases, and setting up productions for each UCR component type. The deployment specialist uses the Installer Wizard for most component installations in both development and production environments.

Launching the Installer Wizard

To access the Installer Wizard:

• Open the Management Portal in a web browser
• Navigate to System Administration > Configuration > HealthShare Installer
• Select the component type to install from the available options
• The wizard presents configuration pages specific to the selected component type

Registry (Hub) Installation

When installing the Registry via the wizard:

• Specify the Hub namespace name (e.g., HSREGISTRY or HUB)
• Configure the Master Patient Index (MPI) settings including matching algorithm parameters
• Enable consent management features
• Select IHE profiles to support (PIX Manager, PDQ Supplier, XDS.b Registry)
• Configure notification and subscription services
• Set up the system index for federation health monitoring
• Review and confirm all settings before the wizard creates the namespace and production

Edge Gateway Installation

When installing an Edge Gateway via the wizard:

• Specify the Edge namespace name (e.g., HSEDGE or EDGE_FACILITY1)
• Select the cache type: Standard Cache (persistent storage in ECR) or Expire-and-Query Cache (temporary storage with on-demand refresh)
• Associate the gateway with one or more facility codes
• Configure IHE profile support (PIX Source, XDS.b Document Source)
• Enable clinical message delivery if required
• Designate whether this Edge Gateway is the Audit Edge for the federation
• Review and confirm all settings

Access Gateway Installation

When installing an Access Gateway via the wizard:

• Specify the Access namespace name (e.g., HSACCESS or ACCESS)
• Configure Clinical Viewer settings and display options
• Set up patient search capabilities via the Registry MPI
• Configure IHE profiles for document retrieval (XCA, XDS.b Consumer)
• Set session timeout and user interface parameters
• Review and confirm all settings

Bus and ODS Installation

The wizard also supports Bus and ODS installation with component-specific options:

• Bus: IHE profile selection for external integration, routing configuration
• ODS: FHIR server configuration, data synchronization settings, analytics enablement

Post-Wizard Steps

After the Installer Wizard completes:

• Verify that the namespace was created correctly in the Management Portal
• Check that the production exists and contains the expected business services and operations
• The production is not yet started; activation is a separate step
• SSL/TLS configuration and endpoint registration must still be performed

---

Overview

While the Installer Wizard provides a graphical step-by-step process, UCR also supports scripted installation methods. These are especially useful for automated deployments, repeatable environment setup, and demonstration environments. The deployment specialist should understand both methods and when to use each.

The InstallDemo Script

InstallDemo is a pre-built script that creates a complete UCR demonstration environment on a single IRIS for Health instance:

• It creates namespaces for the Registry, one or more Edge Gateways, an Access Gateway, and optionally a Bus and ODS
• All components are configured with default settings suitable for demonstration and development
• The script runs from the Terminal or operating system command line
• It accepts parameters to customize the installation (e.g., number of Edge Gateways, facility names)

Running InstallDemo typically involves:

• Opening a Terminal session to the IRIS for Health instance (or an OS command prompt)
• Executing the installer class method with appropriate parameters
• Waiting for the script to complete namespace and production creation
• Verifying the created components in the Management Portal

Command-Line Parameters

Installer scripts accept parameters that control the installation:

• Namespace name: The name of the namespace to create for the component
• Component type: Registry, Edge, Access, Bus, or ODS
• Feature flags: Enable or disable specific features (IHE profiles, FHIR, analytics)
• Facility code: The facility identifier for Edge Gateway installations
• Audit Edge flag: Whether this Edge Gateway is the Audit Edge
• Registry endpoint: The URL of the Registry for Edge and Access Gateway registration

Custom Installer Scripts and Silent Installation

For production deployments, organizations may create custom installer scripts based on the UCR installer API. These scripts encode the specific configuration decisions from the architecture document, ensure identical configuration across multiple environments (dev, test, staging, production), and can include post-installation steps such as SSL/TLS setup and endpoint registration. Version-controlled scripts provide an audit trail of what was installed and when.

Scripted installation supports unattended (silent) execution with no graphical interface required. Scripts can be triggered by deployment automation tools (Ansible, Chef, Puppet), return codes indicate success or failure, and log files capture detailed installation progress for troubleshooting.

When to Use Scripts vs Wizard

• Installer Wizard: Best for initial learning, one-off installations, and when exploring configuration options
• InstallDemo: Best for quickly creating demonstration or development environments
• Custom scripts: Best for production deployments where consistency and reproducibility are paramount
• Exam consideration: Understand both methods and their use cases; the exam may ask when each is appropriate

---

Overview

Installing a UCR component via the Installer Wizard or a script creates the namespace, databases, and production configuration. However, the component is not yet operational. Activation is the process of starting the production and registering the component with the federation. The deployment specialist must understand the activation sequence and the steps required for each component type.

Activation Through the Management Portal

Activation involves starting the production (the interoperability engine within each namespace), registering the component's web service endpoints with the Registry, validating required settings (SSL/TLS, endpoint URLs, credentials), and reporting status to the Registry's system index.

To activate a UCR component in the Management Portal:

• Navigate to the component's namespace
• Go to Interoperability > Configure > Production
• Click the Start button to start the production
• Monitor the production status to confirm all business hosts start successfully
• Check the Event Log for any errors or warnings during startup

Activation Order

Components must be activated in a specific order due to dependencies: 1. Registry (Hub): Must be activated first because all other components register with it 2. Edge Gateways: Activated after the Registry so they can register their endpoints and begin sending patient identity and document notifications 3. Access Gateways: Activated after Edge Gateways so they can discover available data sources for patient queries 4. Bus: Activated after the Registry and relevant Edge/Access Gateways 5. ODS: Activated after Edge Gateways so it can begin receiving data synchronization

Endpoint Registration and Post-Activation Verification

During activation, each component registers its web service endpoints with the Registry. The Registry maintains a service registry of all active endpoints. Edge Gateways register document source and patient identity endpoints, Access Gateways register query endpoints, and the Bus registers integration endpoints. Endpoint URLs must be correct and reachable.

After activating all components:

• Verify all productions are running (green status in the Management Portal)
• Check the System Index on the Registry for the health status of all components
• Test inter-component communication by performing a patient search from the Access Gateway
• Review Event Logs on each component for errors or warnings
• Confirm audit events are flowing to the designated Audit Edge

---

Overview

HealthShare UCR supports FHIR (Fast Healthcare Interoperability Resources) endpoints for standards-based API access to clinical data. FHIR endpoints are typically hosted on the ODS component, though other components may also expose FHIR interfaces. Configuring FHIR endpoints is an increasingly important part of UCR deployment as healthcare organizations adopt modern interoperability standards.

FHIR Server Architecture in UCR

The UCR FHIR server is built into the IRIS for Health platform. It supports FHIR R4 (Release 4) and exposes RESTful endpoints for CRUD operations on FHIR resources. Clinical data stored in SDA format is transformed to FHIR resources on demand. The server supports search parameters, includes, and bulk data export operations.

Configuring the FHIR Server Endpoint

To configure a FHIR endpoint on the ODS:

• Navigate to the ODS namespace in the Management Portal
• Access the FHIR server configuration through Health > FHIR Configuration
• Define the FHIR endpoint URL (e.g., /csp/healthshare/ods/fhir/r4)
• Select the supported FHIR resource types (Patient, Encounter, Observation, Condition, MedicationRequest, etc.)
• Configure the interaction capabilities (read, search, create, update) for each resource type
• Set up the metadata endpoint that publishes the capability statement

OAuth 2.0 Configuration for FHIR

Production FHIR endpoints must be secured with OAuth 2.0. The deployment specialist configures this through the Management Portal:

• Authorization server: Configure via System Administration > Security > OAuth 2.0 > Server Configuration, or integrate with an external identity provider
• Client registration: Register each FHIR client application with a client ID and secret via OAuth 2.0 > Client Configuration
• Scopes: Define FHIR scopes that control resource and operation access (e.g., patient/*.read, patient/Observation.write)
• Token validation: The FHIR server validates access tokens on every request
• SMART on FHIR: UCR supports the SMART on FHIR framework for launch context and authorization

FHIR Endpoint Testing

After configuration, verify the FHIR endpoint using tools such as Postman or curl:

• Issue a GET request to the metadata endpoint and verify the CapabilityStatement lists expected resource types
• Perform a Patient search and verify results from the aggregated clinical data
• Retrieve a specific resource by ID and verify correctness
• Test error handling with invalid tokens, missing parameters, and unsupported operations

---