Skip to main content
Previous sectionNext section

Installing and Configuring a FHIR Server

InterSystems products use a command-line utility to create a FHIR® server and its endpoint. Once created, the same utility can be used to configure the server for specific purposes. Alternatively, you can install and configure a server programmatically.Multiple FHIR servers can be installed in the same namespace.


Before installing a FHIR server, you must consider whether you want to customize it now or in the future. If you install a FHIR server without creating new Interactions and InteractionsStrategy subclasses, you will not be able to perform certain customizations such as adding FHIR operations or modifying how bundles are processed. For information about preparing for these customizations before installing the FHIR server, see Developing Custom Functionality. To view the options that can be configured without creating Interactions and InteractionsStrategy subclasses, see Configuring a FHIR Server.

To run the command-line utility that is used to install a FHIR server:

  1. Open the InterSystems Terminal.

  2. Change to the HSLIB namespace:

    set $namespace = "HSLIB"
    Copy code to clipboard
  3. Enter the following to create a new namespace for the FHIR server. If you have already created an interoperability namespace using the Management Portal, you can skip this step.

    set status = ##class(HS.HC.Util.Installer).InstallFoundation("FHIRNamespace")
    Copy code to clipboard

    Where FHIRNamespace is the name of your new namespace.

    If the process of creating the namespace does not begin, you can check for errors by entering do $SYSTEM.Status.DisplayError(status).

  4. Enter the following to change to the new namespace:

    set $namespace = "FHIRNamespace"
    Copy code to clipboard
  5. To run the installation and configuration utility, enter:

    do ##class(HS.FHIRServer.ConsoleSetup).Setup()
    Copy code to clipboard
  6. Choose option 1) Create a FHIRServer Endpoint.

  7. Follow the prompts for your new endpoint.

Prompt Description
Choose the Storage Strategy: Select the InteractionsStrategy for the endpoint. For InterSystems IRIS for Health, the default storage strategy is the Resource Repository, which stores FHIR data as JSON in dynamic objects.
Choose the Metadata Configuration: Choose the FHIR version for your endpoint.
Important: If you plan to add custom search parameters for your endpoint now or in the future, you must create a custom metadata set first, then choose it at this prompt. For more information, see Custom Metadata Sets.
Do you want to create the default repository endpoint? Enter Y to accept the default base path of your FHIR endpoint. If you want to enter a custom base path of your endpoint, enter N and specify the path. Begin the name of the path with a slash /.
Enter the OAuth Client Name for this Endpoint 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.
Do you want a read-only endpoint? Read-only endpoints are not supported in this release. Enter N.

Configuring a FHIR Server

The command-line utility used to install a FHIR server is also used to configure it. For example, you can route FHIR requests through an interoperability production, control server behavior, or put the server in debug mode during development. These configuration settings can also be modified programmatically by setting the properties of the server’s ConfigData object.

To configure the FHIR server:

  1. From the InterSystems Terminal, change to the FHIR server’s namespace. For example:

    set $namespace = "FHIRNamespace"
    Copy code to clipboard
  2. Run the installation and configuration utility:

    do ##class(HS.FHIRServer.ConsoleSetup).Setup()
    Copy code to clipboard
  3. Choose option 3) Configure a FHIRServer Endpoint.

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

  5. Follow the remaining configuration prompts.

Prompt Description
Endpoint enabled Specify whether the endpoint is enabled. A disabled endpoint rejects requests from FHIR clients.
OAuthClientName: 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.
ServiceConfigName: 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.
RequiredResource: 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.
FHIRSessionTimeout: Maximum number of seconds between requests to the service before any session data is considered stale.
DefaultSearchPageSize: Search result page size to use when a search does not contain a _count parameter.
MaxSearchPageSize: Maximum search result page size to prevent an excessive user-specified page size.
MaxSearchResults: 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.
MaxConditionalDeleteResults: 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.
DefaultPreferHandling: 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 window overrides this default.
DebugMode: For information about setting a debug mode, see Debugging the FHIR Server.

Installing and Configuring Programmatically

For applications that need to install a FHIR server programmatically rather than using the command-line utility, 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 window must be called in order:

HS.FHIRServer.Installer method Description
InstallNamespace()Opens in a new window 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 window Installs an instance of a FHIR Service into the current namespace. This method requires the following arguments:
  • Unique URL of the FHIR endpoint. This is passed as the first argument. Be sure the URL begins with a slash (/).
  • Classname of the FHIR Server’s InteractionsStrategy. This is passed as the second argument.
  • The identifier of the FHIR metadata set used for the FHIR server. This is the third argument. To use base FHIR metadata, pass HL7v30 for STU3 or HL7v40 for R4. If you want the FHIR server to use a custom metadata set, call InstallMetadataSet()Opens in a new window first, then pass its key into InstallInstance(). For more information about creating a custom metadata set, see Custom Metadata Sets.
Two optional arguments can also be passed to InstallInstance():
  • If the FHIR server is using OAuth to control authentication and authorization, enter the OAuth client name as the fourth argument. For more information about using OAuth security, see OAuth 2.0 Authorization.

For example, the following ObjectScript code installs a FHIR server using the default JSON storage strategy for IRIS for Health (Resource Repository).

Set appKey = "/MyFHIRApp/fhir/r4"
Set strategyClass = "HS.FHIRServer.Storage.Json.InteractionsStrategy"
Set metadataConfigKey = "HL7v40"

//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, metadataConfigKey)
Copy code to clipboard

Configuring the FHIR Server Programmatically

The InstallInstance() method creates a HS.FHIRServer.API.ConfigDataOpens in a new window 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 referenceOpens in a new window 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
FeedbackOpens in a new window