Installing and Configuring a FHIR Server

Installing a New FHIR Server

To install and configure a new FHIR server using the Management Portal:

1. Open the FHIR Server Management page:

   • Navigate to Home > Health and click FHIR in the banner.

2. Click the + Add new server tile.

3. Fill out the basic configuration pane as follows:

   Namespace

   Select the name of your foundation namespace from the dropdown.

   Name

   Enter a name for your new FHIR server. Name is a required field when configuring a FHIR server in the Management Portal.

   FHIR Version

   Select a core FHIR package from the FHIR Version dropdown.

   Each package corresponds to a version of the HL7® FHIR® standard. So, for example, to configure a FHIR endpoint that supports FHIR R5, select the hl7.fhir.r5.core@5.0.0 package.

   Choosing the core FHIR package automatically populates the URL field with an appropriate endpoint.

   URL

   An endpoint URL is automatically generated when you choose a FHIR version. You can edit the endpoint’s URL if desired, but ensure that it begins with a forward-slash (/).

   Custom Packages

   Select any custom packages that you want your endpoint to support from the dropdown.

   For more information about packages, see Profiles and FHIR Adaptations. In particular, for information about managing packages programmatically, see Package APIs.

4. Expand the Advanced Configuration pane of the dialog and configure the settings there using the following descriptions as a guide.

   Note:

   Additional configuration options become available in Advanced Configuration once the FHIR server installation has completed.

   First select a Data Organization Strategy and a database architecture:

   Data Organization Strategy

   Select an interaction strategy from the dropdown. If you created a custom interaction strategy, it should appear in the dropdown for you to select.

   • For IRIS for Health and Health Connect, the default interaction strategy is HS.FHIRServer.Storage.JsonAdvSQL.InteractionsStrategy, which stores FHIR data as JSON in dynamic objects.

   • In a HealthShare ODS, always select HS.ODS.FHIR.Storage.InteractionsStrategy.

   Use Namespace default database

   Each FHIR server has a resource database and a resource history database. The default location for these databases is in subfolders of the /mgr/ folder of your installation. If you select this checkbox, you can enter a custom location for each database in the Resource Database Location and Resource History Database Location fields.

   Note:

   Because a FHIR repository can grow to a very large size, the FHIR server has a database expansion strategy built in. On disk, the FHIR resource database begins with an iris.dat file in a folder named:

   resourceDatabaseLocation/FHIRServerNamespaceX001R

   Upon expansion, additional folders containing iris.dat files are created with names that increment the number, for example:

   MYFHIRSERVERX002R

   Similarly, the first folder for a FHIR resource history database is named:

   resourceHistoryDatabaseLocation/FHIRServerNamespaceX001V

   Resource Database/Resource History Database

   If you did not select the default location for the FHIR server’s databases, edit the locations indicated in the Resource Database Location and Resource History Database Location fields. The resource history database contains previous versions of a resource; because these are not accessed as frequently, you could put this database on a slower, less expensive disk.

   Which options appear under Interaction Strategy Settings depend upon which interaction strategy you selected under Data Organization Strategy. Select values for whichever options appear in your FHIR server installation:

   SMART on FHIR Capabilities

   Specify the server’s SMART on FHIR capabilities by entering them as a comma-delimited list into this field. This list does not control the functionality of the endpoint; rather, it specifies the capabilities that are returned in the JSON document when a client appends /.well-known/smart-configuration to the endpoint’s URL. For example:

   launch-ehr, context-ehr-patient, permission-patient, client-public, client-confidential-symmetric
   

   

   For more details about SMART on FHIR capabilities retrieved with Well-Known URIs, see FHIR Authorization Endpoint and Capabilities Discovery using Well-Known Uniform Resource Identifiers (URIs)Opens in a new tab.

   Silence search parameter indexing errors

   Click this checkbox to prevent search parameter indexing errors from aborting FHIR resource save.

   Caution:

   Enable this setting only when strictly necessary.

   Prematurely limit the number of resources...with _max_results

   Clicking this checkbox makes FHIR search queries more efficient by adding a SQL operation TOP N where N is the value of the _maxresults search result parameter.

   Caution:

   Use this setting only if you do not have PostProcessSearch() logic, since post processing filters could remove some or all of the hits from the results set, leading the query to return a number of hits fewer than _maxresults.

   Refer to the hovertext for the field in the management portal for additional discussion of the tradeoffs in selecting this option.

   Suppress FHIR Audit

   Allows a user with permissions to suppress FHIR auditing.

   Functional List Configuration

   Note:

   The Functional List Configuration field displays only for FHIR endpoints that use or extend the HS.FHIRServer.Storage.JsonAdvSQL.InteractionsStrategyOpens in a new tab data organization strategy.

   Comma-delimited string of configurations for functional lists. Each list element is a colon-delimited string of three items:

   • functional list name — the names available in the default interactions strategy are:

     • $current-problems

     • $current-medications

     • $current-allergies

     • $current-drug-allergies

   • list subject search parameter — can be patient, subject, or source

   • list subject resource type — for example, Patient

   The default value is:

   $current-problems:patient:Patient, 
   $current-medications:patient:Patient, 
   $current-allergies:patient:Patient, 
   $current-drug-allergies:patient:Patient
   

   

5. Click Create to create the server and its associated endpoint. To start over instead, click Cancel.

It takes several minutes to create a FHIR server. When the configuration is complete, additional configuration options relating to authorization and requests become available.

Configuring an Existing FHIR Server

You can edit the configuration settings of an existing FHIR server using the FHIR Server Management page of the Management Portal.

To edit the configuration settings of an existing FHIR server using the Management Portal:

1. Open the FHIR Server Management page:

   • Navigate to Home > Health and click FHIR in the banner.

2. In the tile for the desired server, open the menu and choose Edit.

   The various configuration options are described in Basic Configuration Options and Advanced Configuration Options, below.

3. When you have finished modifying the configuration, click Save to save your changes. To start over instead, click Cancel.

Advanced FHIR Server Configuration Options

The Advanced Configuration pane of the dialog has four sections. Expand a section to edit the settings. Use the following descriptions as a guide.

FHIR Server Service Configuration

Data Organization Strategy

You cannot edit the data organization strategy for an existing FHIR server. To use a different strategy, create a new server.

Resource Database/Resource History Database

You cannot edit the database locations from the Management Portal once the databases contain resources.

Service Config Name

To route FHIR requests through an interoperability production before they reach the FHIR server, select the package and name of the business service that will receive the requests. Unless the business service has a custom name, this entry is HS.FHIRServer.Interop.Service.

Note:

For a business service to appear in this dropdown, it must extend the HS.FHIRServer.Interop.ServiceOpens in a new tab class, and it must be included in an interoperability production in this namespace.

For more details, see Interoperability Productions and Adding Business Hosts.

FHIR Server Authorization Settings

OAuth Client Name

Specifies the application (client) name that the FHIR server, as an OAuth resource server, uses to contact the OAuth 2.0 authorization server. Choose the desired OAuth client name from the dropdown list. For more information about OAuth 2.0 support, see OAuth 2.0 Authorization.

Required Resource

To configure the FHIR server such that a FHIR client requires a particular resource in order to send a request, select that resource from the dropdown.

FHIR Server Request Settings

Default Search Page Size

Search result page size to use when a search does not contain a _count parameter.

Max Search Page Size

Maximum search result page size to prevent an excessive user-specified page size.

Max Search Results

Maximum number of resources that can be selected by a search before the server responds to the query with an error. This number only includes resources selected by the actual search; it does not include resources included using an _include search parameter. This value does not affect the size of pages returned by a search. Overly broad searches that select large numbers of resources take a lot of system resources to fulfill, and are probably more broad than the client actually needs.

Default Prefer Handling

Specifies what happens by default when a search request contains an unknown parameter:

• To ignore an unknown parameter in a search request and return a bundle in which the OperationOutcome resource identifies the issue, specify lenient.

• To reject a search request with an unknown parameter and return an error, specify strict.

A FHIR search request that includes the “prefer headerOpens in a new tab” overrides this default.

Max Conditional Deletes

Maximum allowable number of resources to delete using conditional delete. If the conditional delete search finds more than this number of resources, then the conditional delete as a whole is rejected with an HTTP 412 “Precondition Failed” error.

FHIR Session Timeout

Maximum number of seconds between requests to the service before any session data is considered stale.

Interactions Strategy Settings

SMART on FHIR Capabilities

When a client appends /.well-known/smart-configuration to the endpoint’s URL, a JSON document is returned that specifies the SMART on FHIR capabilities of the FHIR server. Specify those capabilities here by entering them as a comma-delimited list into this field. This list does not control the functionality of the endpoint, just the content returned in the JSON document.

For more details about SMART on FHIR capabilities retrieved with Well-Known URIs, see FHIR Authorization Endpoint and Capabilities Discovery using Well-Known Uniform Resource Identifiers (URIs)Opens in a new tab.

Silence search parameter indexing errors

Click this checkbox to prevent search parameter indexing errors from aborting FHIR resource Save.

Caution:

Enable this setting only when necessary.

Functional List Configuration

Note:

The Functional List Configuration field displays only for FHIR endpoints that use or extend the HS.FHIRServer.Storage.JsonAdvSQL.InteractionsStrategyOpens in a new tab Data Organization Strategy.

Comma-delimited string of configurations for functional lists. Each list element is a colon-delimited string of three items:

• functional list name — the names available in the default interactions strategy are:

  • $current-problems

  • $current-medications

  • $current-allergies

  • $current-drug-allergies

• list subject search parameter — can be patient, subject, or source

• list subject resource type — for example, Patient

The default value is:

$current-problems:patient:Patient, 
$current-medications:patient:Patient, 
$current-allergies:patient:Patient, 
$current-drug-allergies:patient:Patient

Resetting a FHIR Server

You can reset a FHIR server. This deletes all data from the server but leaves the server itself intact.

Follow these steps to reset a FHIR server using the Management Portal:

1. Open the FHIR Server Management page:

   • Navigate to Home > Health and click FHIR in the banner.

2. In the tile for the server associated with the desired endpoint, open the menu and choose Reset.

3. In the Reset FHIR Data dialog that appears, click Execute.

Deleting a FHIR Endpoint

You can use the Management Portal either to delete both the FHIR server endpoint and the associated the FHIR data, or to just decommission the endpoint and retain the FHIR data.

To delete or decommission a FHIR endpoint using the Management Portal:

1. Open the FHIR Server Management page:

   • Navigate to Home > Health and click FHIR in the banner.

2. In the tile for the server associated with the desired endpoint, open the menu and choose Delete.

3. Decide whether to remove all data along with the endpoint, and select the corresponding radio button. The deletion options are:

   • Remove all data from the repository, delete the endpoint and FHIR server.

   • Decommission FHIR endpoint, don’t remove data.

4. Click Execute.

Installing a FHIR Server Programmatically

An application can install a FHIR server programmatically. The FHIR server must be installed first, only then can it be configured.

Once you have a foundation namespace, call the methods of HS.FHIRServer.InstallerOpens in a new tab in the order shown below:

pPackageList Parameter

The pPackageList parameter of the InstallInstance()Opens in a new tab method accepts a list of FHIR packages that have been loaded into the system. Often, a package corresponds to a specific Implementation GuideOpens in a new tab, but can also be the core metadata for a version of FHIR. By passing a list of packages to InstallInstance, you can configure an endpoint to support one or more packages. For more about packages, see Profiles and FHIR Adaptations.

To obtain a list of the packages that can be passed into the pPackageList parameter, use the GetAllPackages()Opens in a new tab method in HS.FHIRMeta.Storage.PackageOpens in a new tab. For example, the following code displays the identifiers of the available packages

 set packages = ##class(HS.FHIRMeta.Storage.Package).GetAllPackages()
 for i=1:1:packages.Count()
   { write packages.GetAt(i).id,! }

The result might look like:

hl7.fhir.r5.core@5.0.0
hl7.fhir.r4.core@4.0.1
hl7.fhir.us.core@3.1.0
hl7.fhir.r3.core@3.0.2

Pass in the appropriate package identifiers as arguments to the pPackageList parameter of InstallInstance()Opens in a new tab using $lb. For example:

 Do ##class(HS.FHIRServer.Installer).InstallInstance(
            myURL,
            strategyClass,
            $lb("hl7.fhir.r5.core@5.0.0"))

For details about the APIs used to create FHIR packages, see Package APIs.

Programmatic FHIR Server Install Example

The following ObjectScript code example installs a FHIR server that supports one package and uses the default storage strategy (Resource Repository).

 Set appKey = "/myfhirserver/fhir/r5"
 Set strategyClass = "HS.FHIRServer.Storage.JsonAdvSQL.InteractionsStrategy"
 Set metadataPackages = $lb("hl7.fhir.r5.core@5.0.0")

 //Install a Foundation namespace and change to it
 Do ##class(HS.Util.Installer.Foundation).Install("FHIRNamespace")
 Set $namespace = "FHIRNamespace"

 // Install elements that are required for a FHIR-enabled namespace
 Do ##class(HS.FHIRServer.Installer).InstallNamespace()

 // Install an instance of a FHIR Service into the current namespace
 Do ##class(HS.FHIRServer.Installer).InstallInstance(appKey, strategyClass, metadataPackages)

Configuring a FHIR Server Programmatically

Once you have installed a FHIR server, it can be configured programmatically using the UpdateInstance()Opens in a new tab method of HS.FHIRServer.InstallerOpens in a new tab. This method accepts several arguments that configure the server, including one that accepts the server’s HS.FHIRServer.API.ConfigDataOpens in a new tab object, which contains most of the server’s configuration options.

In addition to the options defined with the ConfigDataOpens in a new tab object, a few of the server’s settings (serviceConfigName, OAuthClient name, and enabled) are specified using a dedicated parameter of the UpdateInstance() method (as shown in the example below). For a list of these configuration options, see the class reference description for UpdateInstance()Opens in a new tab.

The following code configures an existing FHIR server using the UpdateInstance() method.

 Set appKey = "/fhirendpoint/r5"

 //Get and modify FHIR server's configuration object
 Set strategy = ##class(HS.FHIRServer.API.InteractionsStrategy).GetStrategyForEndpoint(appKey)
 Set configData = strategy.GetServiceConfigData()
 Set configData.DefaultPreferHandling = "strict"
 Set configData.DebugMode = 1
 //stringify configData before updating FHIR Server
 Set jsonConfigData = configData.AsJSONString()

 // Define additional settings
 Set enabled = 1
 Set serviceConfigName = "HS.InteropPackage.myBusinessService"
 Set oAuthClient = "OAuthClientName"
 
 // Update FHIR Server
 Do ##class(HS.FHIRServer.Installer).UpdateInstance(appKey, jsonConfigData, enabled, serviceConfigName, oAuthClient)

FHIR Server Command Line Configuration Options

Developers who prefer a command line interface to the Management Portal can use Console Setup in the InterSystems Terminal to perform many of the same actions that are available in the user interface. To run the Console Setup, open the InterSystems Terminal and run:

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

The following sections describe each option that is available in the Console Setup.

Configuring the Profile Validation Server

When you create a FHIR endpoint, an external server named FHIR_Validation_Server is created to perform back-end functions related to profile validation. This server requires a Java 11 development kit. If your JAVA_HOME environment variable does not point to a Java 11 directory, you can use the Management Portal as follows:

1. If necessary, install a supported Java 11 JDK. Make a note of the directory where it has been installed.

2. In the Management Portal, navigate to System Administration > Configuration > Connectivity > External Language Servers.

3. If the FHIR_Validation_Server is running, click Stop.

4. Enter edit mode by clicking FHIR_Validation_Server.

5. On the Edit External Language Server page, in the Java Home Directory field, enter the path to your Java 11 directory.

6. Click Save.

7. Restart the FHIR_Validation_Server by clicking Start.

8. To ensure good performance when you execute validation operations related to previously-imported profiles (including those that are automatically imported), in the Terminal application, switch to your FHIR-enabled namespace and execute the following command:

   do ##class(HS.FHIRServer.Installer).InitializeProfileValidator()
   

   

Optimizing FHIR Server Search Performance

For a FHIR server that uses or extends the Resource Repository, you can optimize the performance of search interaction responses by running the Tune Table utility on the SQL search tables generated for that endpoint. By default, the names of these tables begin with HSFHIR. You can also set custom selectivity values for these tables manually.

When you install a new FHIR server that uses or extends the Resource Repository, a set of default selectivity values are assigned to searchable elements based on the element’s data type. These default selectivity values allow the server to select more efficient query plans when it retrieves resources in response to a search request. Selecting prospective results by beginning with the most selective query parameter minimizes the number of resources each subsequent selection operation must evaluate.

For example, consider the following search request:

GET [base]/Patient?family=halifax&gender=male

Probably, the Resource Repository contains fewer patients with the family name Halifax than patients who are male. Therefore, it is probably most efficient to find the Patients with the family name Halifax first, because then the operation to find males will only have to search through the small subset of patients named Halifax.

If you have upgraded to this version from a version prior to 2023.1 and you are using a preexisting FHIR server, you can set these default selectivity values for your search operations using the SetDefaultSearchTableSelectivities()Opens in a new tab method. Invoke this method in the Terminal, providing the relative path for your FHIR endpoint, as in the following example:

do ##class(HS.FHIRServer.Storage.SearchTableBuilder).SetDefaultSearchTableSelectivities("/csp/healthshare/hsods/fhir/r5")

However, for most preexisting FHIR servers, selectivity values generated by Tune Table are more useful than the default selectivity values set by this method.