Skip to main content

Installing and Configuring a FHIR Server

The Management Portal provides a FHIR Server Management page that allows you to install a new FHIR server and then configure it. Alternatively, you can install and configure a server programmatically. You can also execute many of these tasks using the FHIR Server Management APIOpens in a new tab.

The FHIR server must be installed in a Foundation namespace; multiple FHIR servers can be installed in the same Foundation namespace.

Important:

Before installing a FHIR server, you must consider whether you want to customize it now or in the future. In many cases, a FHIR server using the Resource Repository cannot be customized unless you subclass the InteractionsStrategy before creating the endpoint. For example, modifying how bundles are processed or post-processing search results requires you to subclass the Resource Repository. For information about preparing for these customizations before installing the FHIR server, see Pre-Installation Subclassing.

Prerequisites for installing a new FHIR server:

  • To install a FHIR server, you must have a Foundation namespace. If you do not have a Foundation namespace, follow the creating a foundation namespace procedure to create and activate a foundation namespace before you begin.

  • To interact with the FHIR server management user interface (or use the Management REST API), you must have the %HSAdmin_InstallationManagement resource and the %HS_DB_{NAMESPACE} role assigned for each Namespace you will interact with.

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

  1. Open the Management Portal and open the FHIR server management page in one of the following ways:

    • Navigate to Health > MyNamespace > FHIR Server Management.

    • Navigate to Health and click FHIR in the page header.

  2. Click the + Add New Server tile.

  3. Fill out the form as follows:

    1. Name the new server in the Name field.

    2. Choose the name of your foundation namespace from the Namespace dropdown.

    3. Select a core FHIR package from the FHIR Version dropdown. Each package corresponds to a version of the HL7® FHIR® standard that the endpoint will support. 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 Endpoint field with an appropriate endpoint.

    4. An endpoint URL has been automatically generated based on your choice of the core FHIR package. You can change the endpoint’s URL if desired, but ensure that it begins with a slash (/).

    5. If you want your endpoint to support a custom package, select it from the Custom Packages dropdown. For more information about packages, see Profiles and FHIR Adaptations. In particular, for information about managing packages programmatically, see Package APIs.

    6. Configure the settings in the Advanced Configuration area of the dialog, using the following descriptions as a guide.

      Setting Description
      Data Organization Strategy If desired, select a different InteractionsStrategy for the endpoint. The default interactions strategy isHS.FHIRServer.Storage.JsonAdvSQL.InteractionsStrategy, which stores FHIR data as JSON in dynamic objects. If you created a custom InteractionsStrategy, it appears in this dropdown and you can select it.
      Allow multiple FHIR servers on a single namespace Click this checkbox to allow multiple FHIR servers on a single namespace.
      Use Single Resource Database By default, data for each endpoint in a namespace is stored in two separate databases. If you do not want to maintain separate databases, click this checkbox. When this setting is enabled, all FHIR data is stored in the namespace’s common database files.
      Resource Database If you use separate databases, you can accept the default locations or specify your own by editing the contents of the Resource Database and Resource History Database 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.
      Resource History Database
      Create as Test Server Click this checkbox to create this server as a test server. Test servers are populated with dummy test data and are not intended for production use.
      Create as Production Server Click this checkbox to create this server as a production server.
      Note:

      Production servers do not support the option to load premade bundles.

      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 more details about SMART on FHIR capabilities retrieved with Well-Known URIs, see FHIR Authorization Endpoint and Capabilities Discovery using a 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.

      Use top for _maxresults 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.

  4. When you have finished filling out the form, click Create to create the server and its associated endpoint. To start over instead, click Cancel.

If you prefer to use a command-line interface to install a FHIR server, see Command Line Options.

If you plan to mirror your FHIR server, see Mirroring Considerations for Healthcare Products for special instructions.

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. These configuration settings can also be modified programmatically by setting the properties of the server’s ConfigData object.

To edit the configuration settings of an existing FHIR server via the Management Portal FHIR Server Management page:

  1. Make sure you are in the FHIR server’s namespace.

  2. Navigate to Health > MyNamespace > FHIR Server Management.

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

  4. Fill out the form as follows:

    1. If desired, change the server name in the Name field.

    2. If there are custom packages associated with the selected FHIR version and you want your endpoint to support one of them, select it from the Custom Packages dropdown.

      If this dropdown is not present, there are no custom packages associated with the selected FHIR version.

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

      Note:

      Enabling a custom package automatically triggers the system to re-index search tables when you save your changes.

    3. Configure the desired settings in the Advanced Configuration area of the dialog, using the following descriptions as a guide.

      Setting Description
      Data Organization Strategy If desired, select a different InteractionsStrategy for the endpoint. The default interactions strategy isHS.FHIRServer.Storage.JsonAdvSQL.InteractionsStrategy, which stores FHIR data as JSON in dynamic objects. If you created a custom InteractionsStrategy, it appears in this dropdown and you can select it.
      Resource Database The database that contains current FHIR resource data. If your FHIR server does not use separate databases, this database also contains previous versions of FHIR resources.
      Resource History Database If your FHIR server uses separate databases, this database contains previous versions of FHIR resources.
      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 via 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.
      Max Conditional Deletes Maximum allowable number of resources to delete via 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.
      Default Prefer Handling Specifies what happens by default when a search request contains an unknown parameter. Specify lenient to ignore the unknown parameter and return a bundle in which the OperationOutcome resource identifies the issue. Specify strict to reject the search request and return an error. A FHIR search request that includes the prefer headerOpens in a new tab overrides this default.
      OAuth Client Name Specifies the application name that the FHIR server, as an OAuth resource server, uses to contact the OAuth 2.0 authorization server when needed. Choose the desired OAuth client name from the dropdown list. For more information about OAuth 2.0 support, see OAuth 2.0 Authorization.
      Service Config Name To route FHIR requests through an interoperability production before reaching 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 Session Timeout Maximum number of seconds between requests to the service before any session data is considered stale.
      SMART on FHIR Capabilities A comma-delimited list of the endpoint’s SMART on FHIR capabilities. 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 more details about SMART on FHIR capabilities retrieved with Well-Known URIs, see FHIR Authorization Endpoint and Capabilities Discovery using a 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.

      Use TOP for _maxresults 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.

  5. When you have finished filling out the form, click Save to save your changes. To start over instead, click Cancel.

If you prefer to use a command-line interface to configure a FHIR server, see Command Line Options.

Note:

If you expect to post Bundles containing 10,000 or more entries, you should increase the value of the Web Gateway Server Response Timeout parameter to avoid server timeouts interrupting your data loads.

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:

  1. Make sure you are in the FHIR server’s namespace.

  2. Navigate to Health > MyNamespace > FHIR Server Management.

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

  4. In the Reset FHIR Data dialog, click Execute.

Deleting a FHIR Endpoint

When using the Management Portal to delete a FHIR server endpoint you can choose whether to delete the associated FHIR data or to retain all of its FHIR data. If you prefer, you can use the command line interface instead. For details, see Command Line Options.

To delete an endpoint:

  1. Make sure you are in the FHIR server’s namespace.

  2. Navigate to Health > MyNamespace > FHIR Server Management.

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

  4. Decide whether to remove all data along with the endpoint, and select the corresponding radio button. Deletion options are as follows:

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

    • Decommission FHIR endpoint, don’t remove data.

  5. Click Execute.

Installing Programmatically

For applications that need to install a FHIR server programmatically rather than using the Management Portal, the server must be installed first, then configured.

The FHIR server must run in a foundation namespace, therefore creating a foundation namespace is a prerequisite to installing the FHIR server. Once you have a foundation namespace, the following methods of HS.FHIRServer.InstallerOpens in a new tab must be called in order:

HS.FHIRServer.Installer method Description
InstallNamespace()Opens in a new tab Prepares an existing foundation namespace for the FHIR server; it does not create a new foundation namespace. If called without an argument, the installer assumes the active namespace is a foundation namespace and prepares it for the FHIR server.
InstallInstance()Opens in a new tab Installs an instance of a FHIR Service into the current namespace. This method requires the following arguments:
  • Unique URL of the FHIR endpoint. Be sure the URL begins with a slash (/).

  • Classname of the FHIR server’s InteractionsStrategy.

  • List of FHIR packages, for example, the package for an Implementation Guide like US Core. For details, see pPackageList parameter.

There are also optional parameters that can be passed to InstallInstance(). For complete details on these optional parameters, see InstallInstance()Opens in a new tab

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 Guide, 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 HS.FHIRMeta.Storage.Package.GetAllPackages()Opens in a new tab method. 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

You could then pass in some of these package identifiers as arguments to the pPackageList parameter 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 Install Example

The following ObjectScript code example installs a FHIR server that supports two packages 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 Programmatically

Once you have installed a FHIR server, it can be configured programmatically using the HS.FHIRServer.Installer.UpdateInstance()Opens in a new tab method. 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. For a list of these configuration options, see the class referenceOpens in a new tab. In addition to the options defined with the ConfigData object, a few of the server’s settings (Service Config Name, OAuth Client Name, and Enabled) are specified using a dedicated parameter of the UpdateInstance() method.

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)
Note:

Like all InterSystems IRIS APIs that act on code in a repository, HS.FHIRServer.Installer.UpdateInstance()Opens in a new tab locks the repository to prevent simultaneous configuration activities and holds the lock until configuration is complete. Before performing configuration tasks on your FHIR server using methods other than InterSystems IRIS APIs, execute the Lock() method of the HS.FHIRServer.RepoOpens in a new tab class to lock the repository explicitly, as follows: ##class(HS.FHIRServer.Repo).Lock(). If you completely override an InterSystems IRIS method, remember to use the Lock() method to prevent conflicts.

Command Line 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.

Create FHIRServer Endpoint

Installs a new FHIR server endpoint. You are presented with the following prompts:

  • Choose the Storage StrategyJson is the Resource Repository.

  • Choose the FHIR version for this endpoint — Select the version of the core FHIR specification that your endpoint supports.

  • Enter any package numbers — Packages that have been imported are listed as possibilities. The endpoint can support multiple packages; to specify more than one package, separate the numbers by commas. You can add additional packages later, but you might need to run additional steps if you wait. Use the Upload a FHIR Metadata Package option to add a package to the list.

  • Do you want to create the default repository endpoint — Press Enter if you want to accept the default URL of the endpoint. If you want your endpoint to have a different URL, specify N, and enter the URL (be sure the URL begins with a slash).

  • Enter the OAuth Client Name for this Endpoint — If you are using OAuth 2.0 to secure the endpoint, enter the Client Name of the FHIR server. For more information, see OAuth 2.0 Authorization.

  • Do you want to create separate database files for your FHIR data? — If you specify yes, FHIR data for the endpoint is stored separately from the FHIR data of other endpoints in the same namespace. If you specify no, all FHIR data is stored in the namespace’s database files, even if you have multiple endpoints. If you are creating separate database files, you can accept the default locations or specify alternate locations. The Versions Database contains previous versions of a resource; because these are not accessed as frequently, you could put the Versions Database on a slower, less expensive disk.

Add a profile package to an endpoint

Adds a FHIR package to an existing endpoint so it can support the package’s profiles, search parameters, and other conformance resources. The FHIR package (an NPM-like package) that contains the conformance resources must be uploaded before you can use this option. You can use the Upload a FHIR Metadata Package option to import the FHIR package. Some common packages, for example the US Core Implementation Guide, are already available.

Note that enabling a package triggers the system to re-index search tables.

Display a FHIRServer Endpoint Configuration

Displays the current configuration options of the FHIR server. To modify these configuration options, use the Configure a FHIRServer Endpoint option.

Configure a FHIRServer Endpoint

Allows you to configure the FHIR server endpoint by providing values for each configuration option. For a description of each configuration item, see Configuring a FHIR Server.

Decommission a FHIRServer Endpoint

Deletes a FHIR server endpoint, but retains the FHIR data that has been collected by the endpoint. The SQL tables containing the FHIR data are retained. If you want to delete the endpoint and all of the FHIR data, use the Delete a FHIRServer Endpoint option.

Delete a FHIRServer Endpoint

Deletes a FHIR server endpoint and deletes the endpoint’s FHIR data. If you want to delete the endpoint, but retain the FHIR data that has been collected by the endpoint, use the Decommission a FHIRServer Endpoint option.

Update the CapabilityStatement Resource

Updates the Capability Statement of the FHIR server. For more details, see Modifying the Capability Statement.

Index new SearchParameters for an Endpoint

When you add new search parameters to an existing endpoint using a published or custom package, FHIR clients can use the new parameter to retrieve resources added to the repository after you applied the package. However, resources that existed before you added the new search parameter will not be returned until you re-index the endpoint. If an endpoint has collected a large volume of FHIR data, this option can take a long time to run as it re-processes all existing resources.

Upload a FHIR metadata package

Used to import a FHIR package of JSON files that define conformance resources. You must use this option before the package can be applied to an endpoint. For information about preparing a custom FHIR package for uploading, see Creating a Custom Package.

Delete a FHIR metadata package

Deletes a package from the list of available packages that can be applied to an endpoint. This does not delete the FHIR package’s JSON files from your local system. You cannot delete packages that have been applied to an endpoint.

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()
    
Note:

Do not set the JAVA_HOME environment variable directly to enable the FHIR_Validation_Server; doing so could affect other applications and processes that may rely on the previous value of JAVA_HOME.

Optimizing Search Performance

For a FHIR server which 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 which 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.

FeedbackOpens in a new tab