FHIR Server: An Introduction
The following sections describe the basics of FHIR® server technology in InterSystems products. For an overview of what a default FHIR server supports in InterSystems IRIS for Health, see What is Supported?.
In most cases, implementing a FHIR server in Health Connect refers to the ability to accept requests from a FHIR client into an interoperability production. The default FHIR storage architecture provided with the FHIR server in InterSystems IRIS for Health is not available in Health Connect. Though it is possible to write a custom architecture for a FHIR server in Health Connect, most use cases do not include writing this custom code. For more information about using the endpoint of a FHIR server to receive FHIR requests in Health Connect, see FHIR Productions .
Tracing a FHIR request through the FHIR server provides a good overview of the major architectural features of the server. First, the FHIR request must reach the Service, which ensures that the request conforms to the server's FHIR metadata standards and then routes it to the appropriate component to handle the request. The FHIR request can reach this Service in three ways: from a REST handler, through an interoperability production, or from a server-side ObjectScript application. This Service is unrelated to a business service in an interoperability production.
What the Service does with the request depends on the type of request:
If the request contains an HTTP method and endpoint that correspond to a FHIR interaction, the Service forwards it to the method of the Interactions class that handles that type of FHIR interaction. For example, requests with a read interaction are sent to the Read method of the Interactions class. This Interactions class executes the FHIR interaction, using the InteractionsStrategy class to process the interaction according to the overall purpose of the FHIR server.
For FHIR operations, the Service forwards the request to a special class designed to perform operations. InterSystems IRIS for Health applications using the default Resource Repository offer out-of-the-box support for certain FHIR operations.
If the request contains a bundle of type transaction or batch, the Service forwards the request to a special class that unpacks the bundle to perform the individual HTTP operations.
More About the Service
The Service is a singleton class that allows only one instance of itself to be instantiated for an endpoint. This instantiation occurs when the first FHIR request is sent to the Service by the REST Handler or Business Operation; once instantiated, the Service exists until the process ends. For server applications making FHIR requests programmatically, the app must call HS.FHIRServer.Service.EnsureInstance() to retrieve the Service before sending the first request.
In most cases, the Service class (HS.FHIRServer.Service) is ready to uphold the endpoint's FHIR standard and route requests without being subclassed. Custom logic that determines how the FHIR server behaves is written into the Interactions and InteractionsStrategy subclasses, not the Service.
The methods that manage the Service, including creating a new Service for an endpoint and deleting a Service, belong to the subclass of HS.FHIRServer.API.RepoManager.
More About the InteractionsStrategy
The InteractionsStrategy class dictates the overall strategy for the FHIR server. It is the FHIR server application's backend, creating and implementing the environment in which the FHIR data is processed. The InteractionsStrategy superclass is HS.FHIRServer.API.InteractionsStrategy.
In many cases, the InteractionsStrategy is the "storage strategy" for how the FHIR server stores and retrieves FHIR resources. For example, the Resource Repository in InterSystems IRIS for Health is implemented by a subclass of HS.FHIRServer.API.InteractionsStrategy that creates the resource and index tables used to store and retrieve the FHIR data. In applications that are not storing FHIR data, the strategy might set up an environment that communicates with an external FHIR server or any other custom logic that works with the server's FHIR data.
An InteractionsStrategy is associated with a subclass of HS.FHIRServer.API.RepoManager that manages the Services that use the InteractionsStrategy.
More about the Interactions Class
While the InteractionsStrategy class is the backend of the application, it uses the Interactions class to actually execute the FHIR interactions received by the Service. During this process, the Interactions class often calls methods in the InteractionsStrategy class, especially for structures and logic that are common to the entire FHIR server strategy. Because of their interdependent relationship, the Interactions class and InteractionsStrategy class are subclassed together in a unified approach. The Interactions superclass is HS.FHIRServer.API.Interactions.
The methods in the Interactions class that are called by the Service when processing a FHIR request can also be called directly from a server-side ObjectScript application. For example, a server-side application could call the Add method of the Interactions class rather than sending a POST request to the Service. In bypassing the Service, the server application can bypass any restrictions placed on the FHIR server by the Service's metadata. For example, the server application could populate the FHIR server's storage even though the endpoint is read-only for requests going through the Service.
The Interactions class also keeps track of which specialized classes the Service should use to perform FHIR operations, process bundles, and validate FHIR data. The Service obtains the name of these classes from the Interactions object when it needs to take action.
The message class that the server architecture uses to pass FHIR requests is HS.FHIRServer.API.Data.Request.
The message class that the server architecture uses to pass responses from the server to the FHIR client where the request originated is HS.FHIRServer.API.Data.Response.
For information about accessing the FHIR payload in a message, see Accessing FHIR Payloads.
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:
The following sections describe each option that is available in the Console Setup.
Installs a new FHIR endpoint. You are presented with the following prompts:
Choose the Storage Strategy — Json is the Resource Repository for InterSystems IRIS for Health. If you are using Health Connect and do not have a custom Interactions Strategy, select Json. For more information about creating your own Storage Strategy, see Customizing a FHIR Server.
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.
Adds a 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.
Displays the current configuration options of the FHIR server. To modify these configuration options, use the Configure a FHIRServer Endpoint option.
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.
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.
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.
Updates the Capability Statement of the FHIR server. For more details, see Modifying the Capability Statement.
If you add a package with new search parameters to an existing endpoint, you must run this option before FHIR clients can use those search parameters. 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.
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.
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.
Making REST Calls
When using a REST client to access the InterSystems FHIR server, keep the following in mind:
The base path of an endpoint is: ServerIPAddress:SuperServerPort/baseURL, where:
ServerIPAddress is the IP address of the InterSystems server where the FHIR server is installed.
SuperServerPort is the InterSystems server’s superserver port. You can find this superserver port in the Management Portal by going to System Administration > Configuration > System Configuration > Memory and Startup.
baseURL is the endpoint created during installation. For example, /fhirapp/namespace/fhir/R4.
For example, a REST call to post a resource might look like: