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.
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.
To install a new FHIR server from the Management Portal:
-
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, follow the creating a foundation namespace procedure to create and activate a foundation namespace before you begin.
-
Navigate to Health > MyNamespace > FHIR Configuration. If you do not see the FHIR Configuration menu, make sure you are using a Foundation namespace.
-
Select the Server Configuration card.
-
In the Endpoints pane, click Add Endpoint to create a new FHIR Endpoint.
-
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.
-
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 (/).
-
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.
-
Select the InteractionsStrategy for the endpoint. 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.
-
By default, data for each endpoint in a namespace is stored in two separate databases. If you do not want to maintain separate databases, clear the Use separate databases for FHIR resource storage field; in this case, all FHIR data is stored in the namespace’s common database files. If you use separate databases. you can accept the default locations 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.
-
Select Add.
If you prefer to use a command-line interface to install a FHIR server, see Command 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:
-
Navigate to Health > MyNamespace > FHIR Configuration. Make sure you are in the FHIR server’s namespace.
-
Select the Server Configuration card.
-
Choose the endpoint that you are deleting.
-
Select the Trash Can icon.
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.r4.core@4.0.1
hl7.fhir.us.core@3.3.0
hl7.fhir.uv.vhdir@0.2.0
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.r4.core@4.0.1","hl7.fhir.us.core@3.1.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/r4"
Set strategyClass = "HS.FHIRServer.Storage.Json.InteractionsStrategy"
Set metadataPackages = $lb("hl7.fhir.r4.core@4.0.1","hl7.fhir.us.core@3.1.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)
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 Strategy — Json 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.
If the package contains new search parameters, you must run the Index new SearchParameters for an Endpoint option when you are done.
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
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.
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/r4")
However, for most preexisting FHIR servers, selectivity values generated by Tune Table are more useful than the default selectivity values set by this method.
