FHIR Server

A FHIR Server is a software application that implements the FHIR (Fast Healthcare Interoperability Resources) standard, enabling healthcare systems to store, access, exchange, and manage healthcare data in a standardized manner.

Intersystems IRIS can store and retrieve the following FHIR resources:

• Resource Repository – IRIS Native FHIR server can effortlessly store the FHIR bundles/resources directly in the FHIR repository.
• FHIR Facade - the FHIR facade layer is a software architecture pattern used to expose a FHIR-compliant API on top of an existing one (often non-FHIR). It also streamlines the healthcare data system, including an electronic health record (EHR), legacy database, or HL7 v2 message store, without requiring the migration of all data into a FHIR-native system.

What is FHIR?

Fast Healthcare Interoperability Resources (FHIR) is a standardized framework created by HL7 International to facilitate the exchange of healthcare data in a flexible, developer-friendly, and modern way. It leverages contemporary web technologies to ensure seamless integration and communication across various healthcare systems.

Key FHIR Technologies

• RESTful APIs: For resource interactions.
• JSON and XML: For data representation
• OAuth2: For secure authorization and authentication.

FHIR is structured around modular components called resources, each representing a specific healthcare concept, including the following:

• Patient: Demographics and identifiers.
• Observation: Clinical measurements (e.g., vitals, labs).
• Encounter: Patient-provider interactions.
• Medication, AllergyIntolerance, Condition, etc.

FHIR Facade:

A FHIR facade is an architectural layer that exposes a FHIR-compliant API on top of an existing non-FHIR system (e.g., a legacy EHR, HL7 v2 store, or custom database), without requiring you to store data directly as FHIR.

It enables on-demand transformation of legacy data into FHIR resource format (JSON or XML), facilitating interoperability while preserving your existing backend infrastructure.

The FHIR Facade receives and sends FHIR resources, relying on the Prebuilt FHIR server architecture without persisting them into the resource repository. Therefore, it provides a granular level of control over your logic.

IRIS FHIR Facade Architecture

1. HS.FHIRServer.RestHandler This class receives and processes all incoming FHIR requests from client systems, dispatching them afterwards to the HS.FHIRServer.Service class for further handling.
2. HS.FHIRServer.Service This core singleton class is responsible for handling FHIR resources and bundles. It determines the type of incoming request and routes it appropriately to the following directions:

• FHIR Interactions: Handled by HS.FHIRServer.Storage.JsonAdvSQL.Interactions. It is an Interactions class, which serves as the primary interaction handler.
• Bulk FHIR Bundle Transactions: Managed by HS.FHIRServer.DefaultBundleProcessor.
• FHIR Operations: Processed by HS.FHIRServer.API.OperationHandler.

FHIR Facade Implementation

Prerequisites for Creating a FHIR Server and Implementing a FHIR Facade in InterSystems IRIS

Before creating a FHIR server and implementing the FHIR facade in InterSystems IRIS, ensure the following configurations are properly set up:

1. Configure and enable the FHIR Foundation in the required namespace.
2. Customize the FHIR implementation classes, including those below
   • RepoManager
   • InteractionStrategy
   • Interactions

FHIR Foundation configuration

Step 1: Activate the FHIR Foundation

First, you should activate the FHIR Foundation. To do that, take the following steps:

1. Switch to the HSLIB namespace in the System Management Portal.
2. Navigate to the Health menu.

There, you will find a list of available foundation namespaces.

For this demo, we will be using the LEARNING namespace (database) as an example.

At the top of the screen, click "Installer Wizard" to view the status of the foundation namespace.
Ensure that your namespace is marked as "Activated". If not, click the "Activate" button to enable it.

Manual Configuring of the Foundation Namespace

In case your namespace does not appear on the Installer Wizard page, you can manually configure it by following the steps below:

1. Click Configure Foundation.
2. Enter the required details.
3. Activate the namespace (e.g., the one you have just configured).

Note: Before adding the foundation namespace, ensure the following prerequisites are met:

• All HealthShare (HS) packages, routines, and globals* are correctly mapped to your target namespace.
• All required roles are created and properly assigned.

Otherwise, you may encounter unexpected errors during configuration.

Once configured, you can see the namespace in the Foundation list.

Programmatic Foundation Configuration

Run the install class method below:

Do ##class(HS.Util.Installer.Foundation).Install(“FoundationNamespace”)

Well done! The foundation namespace has been successfully configured and activated! With this setup in place, you are now ready to proceed.

Since all configuration-related activities are automatically recorded in log files, you can refer to them for troubleshooting if you encounter any issues during the configuration process. (Check out the Analyzing HS Log Files for Configuration section for details.)

The next step is to customize the FHIR implementation classes to meet your specific integration and processing requirements.

Customizing FHIR Implementation Classes

The IRIS FHIR server architecture allows a flexible customization of its FHIR implementation classes regardless of whether you are extending the Resource Repository or writing a custom backend. It can be done in two ways:

1. Facade Approach (Recommended): You can customize the prebuilt FHIR classes to interact directly with your FHIR resources. This method aligns with the Facade design pattern by abstracting underlying systems through FHIR interfaces. 
2. Interoperability Routing Approach: You may configure the FHIR server to forward incoming requests to IRIS Interoperability at the initial stage of request processing. This allows you to leverage interoperability components for custom logic and routing.With this approach, you can configure the Interoperability Service class directly within the FHIR server setup under “Service Config Name.” The FHIR server will then redirect the request to your Interoperability production environment.

Note: For this Interoperability routing method, only HS.FHIRServer.Interop.Service or its subclasses are supported. IRIS does not permit the use of other general business service classes.

Generally, a FHIR server resource repository without an interoperability production can achieve significantly faster performance.

At this point, let’s proceed to creating custom classes.

Customize the Prebuilt in Classes

To begin customizing the FHIR Server, create subclasses of the classes listed below. You can modify their behavior by adjusting parameters, altering logic, or rewriting functionality as required to meet your specific needs.

Note: starting from version IRIS 2024.1, the interaction logic has been updated. You can find the details of the new implementation below. For backward compatibility, both the legacy and updated classes are still available. However, if you work with the latest version, it is recommended to use the updated implementation.

Starting from version 2024.1:

• HS.FHIRServer.Storage.JsonAdvSQL.Interactions
• HS.FHIRServer.Storage.JsonAdvSQL.InteractionsStrategy
• HS.FHIRServer.Storage.JsonAdvSQL.RepoManager

For versions prior to 2024.1:

• HS.FHIRServer.Storage.Json.Interactions
• HS.FHIRServer.Storage.Json.InteractionsStrategy
• HS.FHIRServer.Storage.Json.RepoManager

If you are writing an entirely custom backend logic to handle your FHIR server architecture instead of employing the Resource Repository, you should subclass the architecture superclasses:

• HS.FHIRServer.API.Interactions
• HS.FHIRServer.API.InteractionsStrategy 
• HS.FHIRServer.API.RepoManager

Before customizing the classes, let's take a moment to understand the concept of FHIR interactions first.

What is FHIR Interactions?

FHIR interactions are standard operations defined by the FHIR (Fast Healthcare Interoperability Resources) specification that a client can perform on FHIR resources via a RESTful API.

These interactions define how clients and servers communicate, including retrieving, creating, updating, or deleting healthcare data represented as FHIR resources.

Common FHIR Interactions

Below, we stated a list of the main types of FHIR interactions:

• Read: Retrieves a resource by its ID (e.g., GET /Patient/123).

• Vread (Versioned Read): Retrieves a specific version of a resource (e.g., GET /Patient/123/_history/2).

• Update: Replaces an existing resource (e.g., PUT /Patient/123).

• Patch: Partially updates a resource (e.g., PATCH /Patient/123).

• Delete: Removes a resource (e.g., DELETE /Patient/123).

• Create: Adds a new resource (e.g., POST /Patient).

• Search: Queries resources based on parameters (e.g., GET /Patient?name=Ashok).

• History: Retrieves the change history for a resource or resource type (e.g., for a resource: GET /Patient/123/_history; for all resources: GET /_history).

• Capabilities: Returns a CapabilityStatement showing what the FHIR server supports (e.g., GET /metadata).

Let’s continue customizing our classes.

These three major classes form a hierarchical chain, where they are linked to one another, and together they establish the foundational infrastructure for your FHIR server implementation.

Interaction Class

  HS.FHIRServer.Storage.JsonAdvSQL.Interactions is the core class that serves as a backbone for handling FHIR interactions through the InteractionsStrategy class.It facilitates communication between the service class and the resource repository.

This class provides API methods to interact with the FHIR repository at the resource level:

• Add(): Creates and stores a new resource in the FHIR repository.
• Delete(): Removes an existing resource from the repository.
• Read(): Retrieves a specific resource from the repository.
• LoadMetadata(): Loads metadata used to define the Capability Statement. (Check out the Modify Capability Statement section for configuration details.)

This is not a full list of methods.

The methods in the Interactions class, which are invoked by the Service (HS.FHIRServer.Service.cls) class during FHIR request processing, can also be called directly from a server-side Object Script application. For instance, instead of sending a POST request to the service, a server-side application can call the Add() method of the Interactions class rather than sending a POST request to the Service.

Interaction Strategy Class

The HS.FHIRServer.JsonAdvSQL.InteractionsStrategy class defines the overall strategy and backend logic for the FHIR server. It serves as the storage strategy, determining how FHIR resources are stored and retrieved.

Each InteractionsStrategy is associated with a subclass of HS.FHIRServer.API.RepoManager, which handles the services that work with this strategy.

Additionally, you must configure the two parameters in the InteractionsStrategy class mentioned below:

1. StrategyKey: Assigns a unique key used by both InteractionsStrategy and RepoManager (e.g., Parameter StrategyKey As %String = "MyFacade").

      2. InteractionsClass: Specifies the custom interactions class to use (e.g., Parameter InteractionsClass As %String = "FHIRFacade.Storage.JsonAdvSQL.Interactions").

Repo Manager Class

The HS.FHIRServer.Storage.JsonAdvSQL.RepoManager Resource Repository is the default storage strategy for a FHIR server. It allows you to install a fully functional FHIR server without any additional development tasks. This Repo automatically stores FHIR data received by the server. This class can create new repositories, configure FHIR databases, formulate a strategy, etc.

Besides, you must configure a parameter in the RepoManager class stated below:

1. StrategyKey: Assigns a unique key used by both InteractionsStrategy and RepoManager.

Customizing the Interactions Class

To begin the process, let's look at the Interactions class first.

1. Create a Custom Class Extend the HS.FHIRServer.Storage.JsonAdvSQL.Search class to define your custom behavior.
2. Override the Add() Method for Specific Resource Types Instead of storing the resource in the default repository, redirect handling to your custom implementation (e.g., when the resourceType is Patient). To achieve it, override the Add() method in your custom class.
3. Set Required Metadata on the Resource Object As a part of this customization, ensure that particular metadata fields are set on the pResourceObj. Failing to do so may result in unexpected errors. Required fields include the following:

   Set pResourceObj.meta = {}
   Set pResourceObj.meta.versionId = 1
   Set pResourceObj.meta.lastUpdated = $ZDT($H, 3, 7)

    

It will ensure proper resource versioning and timestamping, required for the FHIR server to function correctly.

Include HS.FHIRServer
Class MyFacade.HS.FHIRServer.Storage.JsonAdvSQL.Interactions Extends HS.FHIRServer.Storage.JsonAdvSQL.Search
{
Method Add(pResourceObj As %DynamicObject, pResourceIdToAssign As %String = "", pHttpMethod = "POST") As %String
{
    If pResourceObj.resourceType="Patient" {
        Set sc = ##class(MyFacade.FHIRFacade.Patient.Utils).Create(pResourceObj)
        If $$$ISOK(sc) {
            Return pResourceObj.Id
        }
    }
    Else {
        $$$ThrowFHIR($$$HSFHIRErrResourceNotSupported,pResourceObj.resourceType)
    }
    }
}

/// My custom class to handle the FHIR resource. Here I can modify and store data into my classes/global 
Class MyFacade.FHIRFacade.Patient.Utils Extends %RegisteredObject
{

ClassMethod Create(pResourceObj)  As %Status
{
    ///
    /// Store logic 
    /// You have to set the values below as mandatory key-value pairs in pResourceObj
    Set pResourceObj.Id=11
    Set pResourceObj.meta = {}
    Set pResourceObj.meta.versionid=1
    Set pResourceObj.meta.lastUpdated = $ZDT($H,3,7)
    Set pResourceObj.meta.LastModified = $ZDT($H,3,7)
}

}

Note:In IRIS, once the FHIR server is configured and enabled, it intentionally caches instances of your StrategyInteractions and Interaction classes to help improve overall performance.

Before proceeding with the next customization step,it is simportant to understand what a CapabilityStatement is and how to define one for your FHIR server.

Capability Statement

A FHIR server's Capability Statement  is client-facing metadata that describes the functionality the FHIR server supports. It contains details that FHIR clients can retrieve about the server's behavior, operations it supports, and how it processes FHIR requests.

Customizing the FHIR Server CapabilityStatement

As you customize your FHIR server (FHIR Facade), you should also update the Capability Statement so that FHIR clients have an accurate description of its capabilities. You have two options for how to do it.

Typically, you can access the CapabilityStatement by invoking the REST API call to your server with the metadata resource (your_FHIRServer_URL/metadata).

E.g., GET http://127.0.0.1:52782/fhirapp/r4/metadata

InterSystems IRIS provides two ways to customize the CapabilityStatement of the FHIR server architecture:

1. Overriding Methods in a Custom InteractionStrategy Class (Recommended)

This is the preferred and most flexible approach since it gives you greater control over how the CapabilityStatement is generated.

The CapabilityStatement is automatically regenerated when certain FHIR server behaviors change and is cached to improve performance.Therefore, the statement is usually generated during FHIR server activation or deactivation, etc.

IRIS offers several methods to update different parts of the CapabilityStatement, where the key method is the following:

GetCapabilityTemplate()

This method is used to customize basic details (e.g., name, version, publisher, description, status, etc). You can also override the GetCapabilityTemplate() method in your custom InteractionStrategy class to return a modified structure that suits your implementation.

LoadMetadata()

This method is a part of the Interactions class and can be invoked by the InteractionStrategy class to generate the CapabilityStatement.

You can configure your custom CapabilityStatement either directly within this method or by delegating the logic to another class and calling it from within LoadMetadata().

Customization Example

I customized the LoadMetadata() method as follows:

1. I created a custom class (FHIRFacade.Utils) to define and hold the CapabilityStatement.
2. I validated the statement and saved it to the ..metadata and ..metadataTime properties.

Method LoadMetadata() As %DynamicObject
{
    #; get your capability statement by calling your class method
    Set metadata = ##class(FHIRFacade.Utils).FHIRFacadeCapabilityStatement()
    Set GLOBAL = ..strategy.GetGlobalRoot()
    if metadata="" {
        $$$ThrowFHIR($$$HSFHIRErrMetadataNotConfigured,$$$OutcomeIs(503, "fatal", "transient"))
    }
    if @GLOBAL@("capability", "time") '= ..metadataTime {
        Set ..metadata = ##class(%DynamicObject).%FromJSON(metadata)
        Set ..metadataTime = $Get(@GLOBAL@("capability", "time"),$ZDT($H,3,7))
    }
    Return ..metadata
}

As I previously mentioned, the FHIR server caches the CapabilityStatement to improve performance. It means that any changes you make to the configuration or implementation can not take effect until the CapabilityStatement is explicitly updated.

To update the CapabilityStatement, take the steps below:

1. Open the IRIS terminal and execute the following command:

DO ##class(HS.FHIRServer.ConsoleSetup).Setup()

2. From the menu, select Option 7: Update the CapabilityStatement Resource.
3. Choose the FHIR endpoint you wish to update.
4. Confirm the update when prompted.

Alternatively, you can employ the class method mentioned below to update the CapabilityStatement:

ClassMethod UpdateCapabilityStatement(pEndPointKey As %String = "/csp/healthshare/learning/fhirmyfac/r4")
{
    #dim strategy as HS.FHIRServer.API.InteractionsStrategy = ##class(HS.FHIRServer.API.InteractionsStrategy).GetStrategyForEndpoint(pEndPointKey)
    if '$IsObject(strategy) {
    $$$ThrowFHIR($$$GeneralError, "Unable to create Storage Strategy Class")
    }
    Set interactions = strategy.NewInteractionsInstance()
    do interactions.SetMetadata( strategy.GetMetadataResource() )
}

You can manually retrieve, modify, and upload the CapabilityStatement for a FHIR server endpoint. This approach enables complete control over the statement’s structure and content.

Steps to Retrieve and Export the CapabilityStatement:

1. Get the interaction strategy for your FHIR endpoint.
2. Create a new interactions instance.
3. Load the existing CapabilityStatement.
4. Export it to a local JSON file:

ClassMethod UpdateCapabilityStatamentViaFile()
{
    Set strategy = ##class(HS.FHIRServer.API.InteractionsStrategy).GetStrategyForEndpoint("/fhirapp/r4")
    Set interactions = strategy.NewInteractionsInstance()
    Set capabilityStatement = interactions.LoadMetadata()
    Do capabilityStatement.%ToJSON("c:\localdata\MyCapabilityStatement.json")
}

5. Edit the exported JSON file according to your configuration. Then run the code below to load the updated CapabilityStatement into the FHIR server:

ClassMethod LoadCapabilitystatmentToFHIR(){ 
      set strategy = ##class(HS.FHIRServer.API.InteractionsStrategy).GetStrategyForEndpoint("/fhirapp/r4")
      set interactions = strategy.NewInteractionsInstance()
      set newCapabilityStatement = {}.%FromJSONFile("c:\localdata\MyCapabilityStatement.json")
      do interactions.SetMetadata(newCapabilityStatement)
}

Configure a FHIR Server Endpoint

The FHIR configuration interface and setup process have undergone significant changes in version 2025.1, which serves as the reference for this documentation

• In 2025.1: To add a FHIR endpoint, navigate to IRIS Management Portal → Health > FHIR Server Management > FHIR Configuration
  • URL: /csp/healthshare/learning/fhirfac/r4
  • Namespace: select your namespace
  • FHIR Version: select FHIR version

• In Versions Before 2025.1: The navigation path was IRIS Management Portal → Health > FHIR Configuration Example endpoint: /csp/healthshare/learning/fhirfac/r4

Advanced Configuration

The Advanced Configuration section allows you to define a custom interaction strategy class after providing the required details:

Additional Configurations

You can configure the following settings if needed. Otherwise, the system will proceed with the default values:

Finally, click Create to start the configuration process. Please note that it may take some time since the system will perform the tasks below:

1. FHIR Server Database Setup

• Resource Database: Stores the current FHIR resources.

• History Database: Maintains historical versions of the resources.

This setup creates a couple of databases to store the resources.

2. Global Mappings and Additional Configuration The system automatically establishes global mappings and applies additional configuration settings required for the FHIR server.

The system is now ready to receive FHIR requests and send responses accordingly.

Analyzing HS Log Files for Configuration 

Foundation Namespace Activation Log Files

During the activation of the Foundation namespace via the Installer Wizard, InterSystems IRIS automatically generates a set of log files. These files capture detailed information about the actions performed during the setup of the foundational components required for the FHIR server.

These logs are invaluable for understanding and troubleshooting the configuration process since they typically include the following:

• High-level installation events related to the FHIR server configuration.
• Namespace-specific configuration details, showing what was set up or modified in each targeted namespace.

The log file names demonstrate a pattern. They begin with HS.Util.Installer, followed by the namespace name, a hyphen (-), an integer, and the .log extension. For example: HS.Util.Installer.HSSYS-0.log.

Note: An integer count will increment each time the foundation is activated.

To programmatically retrieve these directories, take the steps below:

• Use $system.Util.InstallDirectory() to get the IRIS installation directory.
• Employ $system.Util.ManagerDirectory() to obtain the full path to the /mgr/ directory.

Common Log Files:

• HS.Util.Installer.1.log
• HS.Util.Installer.HSSYS-0.log
• HS.Util.Installer.HSCUSTOM-0.log
• HS.Util.Installer.HSLIB-0.log
• HS.Util.Installer.HSSYSLOCALTEMP-0.log

If you encounter any issues during installation or configuration, review these log files for detailed diagnostic information.

Note: Always review these log files to ensure that no errors are present after every IRIS upgrade.

Additionally, the IRISFHIRServerLogs application on Open Exchange provides a web interface for viewing these logs.

Debugging the FHIR Server

InterSystems IRIS provides a debug mode for the FHIR server to facilitate effortless debugging.

Understanding Class Caching in InterSystems IRIS FHIR Server

In InterSystems IRIS, once the FHIR server is configured and enabled, it starts intentionally caching instances of your StrategyInteractions and interaction classes to improve overall performance.

However, due to this caching mechanism, any changes made to your subclasses can not be reflected once the classes have been cached. In other words, updates to your custom logic will not take effect unless the FHIR server creates new instances of those classes.

To ensure your modifications are reflected during development or testing, you can enable debug mode, which forces the server to produce a new instance for each request.

Enabling Debug Mode via IRIS Shell

Take the steps below to enable debug mode using the IRIS terminal:

1. Open the IRIS Terminal and run the following command:

Do ##class(HS.FHIRServer.ConsoleSetup).Setup()

2. From the menu, select "Configure a FHIR Server Endpoint".
3. When prompted, choose the endpoint you wish to configure. In the Edit FHIR Service Configuration section, locate the Debug Mode setting. Then, change its value from 0 to 7 to enable full debug mode.

This setting also enables the following:

• Allow Unauthenticated Access
• New Service Instance per request
• Include Tracebacks in responses

4. Save the configuration.

Capability Statement Updates

The Do ##class(HS.FHIRServer.ConsoleSetup).Setup() command is a versatile tool and is not limited to debugging purposes only. It can also be used for the following:

• Configuring, updating, and decommissioning FHIR endpoints.
• Updating the Capability Statement

Useful Macros, Classes, and Globals

Macros

• $$$ThrowFHIR: Used to throw FHIR-compliant exceptions within the server logic.
• $$$HS*: A set of macros that define standard FHIR-relevant error messages.

Classes

• HS.FHIRServer.Installer: Provides relevant class methods to install.

• HS.FHIRServer.Tools.CapabilityTemplate: Offers templates and helper methods for constructing and customizing the FHIR CapabilityStatement.
• HS.FHIRServer.API.OperationHandler: Manages custom FHIR operations on the server.
• GetMetadataResource(): Modifies or extends the CapabilityStatement returned by the FHIR server if you override this method in your custom class.
• HS.Util.Installer.Foundation
• HS_HC_Util_Installer.Log: internally stores details from the HS.Util.Installer.*.log files.

Globals

• ^HS.FHIRServer.*: Stores FHIR server configuration data and resource instances.
• ^FSLOG: Stores FHIR server log entries for auditing and debugging. The FSLog Open Exchange application can provide a web-based view of these logs.
• ^%ISCLOG: Enables HTTP request logging at various levels. Below you can see an example of how to activate detailed logging:

Enable logging:

Set ^%ISCLOG = 5

Set ^%ISCLOG("Category","HSFHIR") = 5

Set ^%ISCLOG("Category","HSFHIRServer") = 5

Disable logging:

set ^%ISCLOG=1

• ^FSLogChannel: To enable logging in the foundation namespace. This global specifies the types of logging information that should be captured. Once ^FSLogChannel is set, the system will begin storing logs in the ^FSLOG global. To disable the logs, delete the global kill ^FSLogChannel.

Available channelType values include "Msg", "SQL", "_include", and "all".

Example: Set ^FSLogChannel("all") = 1; Enables logging for all channel types.

Common Errors and Solutions

"Class Does Not Exist" Error on Foundation:

Even with all configurations done correctly, you may sometimes encounter the following error. When it occurs, remember to verify the following:

1. Ensure that all %HS_DB_* roles are created and properly mapped to the foundation namespace.
2. Check the HS.Util.Installer.* log files for both the HSSYS namespace and your target namespace.

 This article provides an overview of the basic FHIR facade configuration.