Skip to main content
Previous sectionNext section

Installing and Configuring a FHIR Server

The Management Portal provides a Server Configuration page that allows you to install a new FHIR® server and then configure it. Alternatively, you can install and configure a server programmatically.

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


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.

To install a new FHIR server from the Management Portal:

  1. Open the Management Portal and switch to the Foundation namespace where you want the FHIR server installed. If you do not have a Foundation namespace, go to Health, and select Installer Wizard from the top menu bar. The Configure Foundation button allows you to create a new Foundation namespace. Be sure to activate the namespace after creating it.

  2. Navigate to Health > FHIR Configuration > Server Configuration. If you do not see the FHIR Configuration menu, make sure you are using a Foundation namespace.

  3. In the Endpoints pane, click Add Endpoint to create a new FHIR Endpoint.

  4. Select a core FHIR package. Each package corresponds to a version of the FHIR standard which the endpoint will support. So, for example, to configure a FHIR endpoint that supports FHIR R4, select the hl7.fhir.r4.core@4.0.1 package.

  5. Review the endpoint URL that has been autogenerated according to your choice of the core FHIR package. You can change the endpoint’s URL, but ensure that it begins with a slash (/).

  6. If you want the endpoint to support additional packages, select them from the Additional Packages drop-down list. For more information about packages, see Profiles and FHIR Adaptations.

  7. Select the InteractionsStrategy for the endpoint. For InterSystems IRIS for Health, the default interactions strategy is the Resource Repository (HS.FHIRServer.Storage.Json.InteractionsStrategy), which stores FHIR data as JSON in dynamic objects. If you created a custom InteractionsStrategy, select it from the list.

  8. By default, data for each endpoint in a namespace is stored in a separate database. If you do not want to maintain separate databases, clear the Use separate databases for FHIR resource storage field. You can accept the default locations of the separate databases, or specify your own. 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.

  9. Select Add.

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

Configuring a FHIR Server

Once you have installed a FHIR Server, you can configure its settings using the Server Configuration page of the Management Portal. These configuration settings can also be modified programmatically by setting the properties of the server’s ConfigData object.

To configure the FHIR server:

  1. In the Management Portal, navigate to Health > FHIR Configuration > Server Configuration. Make sure you are in the FHIR server’s namespace.

  2. Choose the endpoint of the FHIR server that you are configuring.

  3. When the page expands, scroll down and select the Edit button.

  4. Configure the settings, using the following descriptions as a guide.

Setting Description
Enabled Specify whether the endpoint is enabled. A disabled endpoint rejects requests from FHIR clients.
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 Delete Results 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.
FHIR Session Timeout Maximum number of seconds between requests to the service before any session data is considered stale.
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 header 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. For more information about OAuth 2.0 support, see OAuth 2.0 Authorization.
Required Resource If you specify an InterSystems security resource, FHIR clients must have privileges to the resource to perform interactions on the server. For more information, see Adding Authorization Requirements.
Service Config Name To route FHIR requests through an interoperability production before reaching the FHIR server, enter 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. For more details, see FHIR Productions.
Allow Unauthenticated Access Allows all FHIR requests to reach the server, ignoring authentication and authorization strategies.
New Service Instance Instantiates a new Service object for every FHIR request.
Include Tracebacks The FHIR server responds to a FHIR request by sending a stack trace in an OperationOutcome resource.

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

Deleting a FHIR Endpoint

By default, using the Management Portal to delete an FHIR server endpoint also deletes the FHIR data associated with the endpoint. However, if you want to delete an endpoint but retain all of its FHIR data, you can use the command line interface to decommission the endpoint rather than delete it. For more information about using the command line interface to decommission an endpoint, see Command Line Options.

To delete an endpoint:

  1. In the Management Portal, navigate to Health > FHIR Configuration > Server Configuration. Make sure you are in the FHIR server’s namespace.

  2. Choose the endpoint that you are deleting.

  3. Select the Trash Can icon.

Installing and Configuring 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.Installer must be called in order:

HS.FHIRServer.Installer method Description
InstallNamespace() 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() 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 toInstallInstance(). For complete details on these optional parameters, see InstallInstance()

pPackageList Parameter

The pPackageList parameter of the InstallInstance() 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() 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,! }
Copy code to clipboard

The result might look like:

Copy code to clipboard

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(appKey, strategyClass, $lb("hl7.fhir.r4.core@4.0.1","")
Copy code to clipboard

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 for InterSystems IRIS for Health (Resource Repository).

Set appKey = "/MyFHIRServer/fhir/r4"
Set strategyClass = "HS.FHIRServer.Storage.Json.InteractionsStrategy"
Set metadataPackages = $lb("hl7.fhir.r4.core@4.0.1","")

//Install a Foundation namespace and change to it
Do ##class(HS.HC.Util.Installer).InstallFoundation("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)
Copy code to clipboard

Configuring the FHIR Server Programmatically

The InstallInstance() method creates a HS.FHIRServer.API.ConfigData object when it creates the FHIR server endpoint. You can control the behavior of the FHIR server by modifying the properties of this object. Refer to the class reference or the configuration utility’s settings for a description of these properties.

For example, the code to change the debug mode of the FHIR server would retrieve the FHIR server’s configData object, modify the DebugMode property, and then save the ConfigData object. The ObjectScript code might look like:

Set appKey = "/MyFHIRApp/fhir/r4"
Set strategy = ##class(HS.FHIRServer.API.InteractionsStrategy).GetStrategyForEndpoint(appKey)
Set configData = strategy.GetServiceConfigData()
Set configData.DebugMode = 4
Do strategy.SaveServiceConfigData(configData)
Copy code to clipboard