Skip to main content

FHIR Interoperability Adapter

Not all solutions require a FHIR server that routes requests to an internal repository. For example, an implementation may need to receive an HL7® FHIR® request and forward it to an external FHIR server without ever storing its payload in an InterSystems product. In cases where you need to process a FHIR request without leveraging the internal repository of a FHIR server, you can use the FHIR Interoperability Adapter to receive requests into an interoperability production. For Health Connect implementations that are not licensed to install a FHIR server with a repository, incoming FHIR requests are processed by installing a FHIR interoperability Adapter.

Installing the FHIR Interoperability Adapter creates a new interoperability REST endpoint that uses special business hosts to process FHIR requests in a production. Note that this interoperability REST endpoint does not appear with the FHIR server endpoints in the Management Portal.

Installing an Adapter

To install a FHIR Interoperability Adapter:

  1. Create a namespace with an interoperability production.

  2. Open the InterSystems Terminal and change to the namespace that you just created. For example, enter:

     set $namespace = "myFHIRNamespace"
  3. Run the following command, specifying the URL of the interoperability REST endpoint:

     set status = ##class(HS.FHIRServer.Installer).InteropAdapterConfig("/MyEndpoint/r5")

    The URL of the Adapter’s endpoint must start with a slash (/).

  4. To ensure the command executed successfully, enter:

     write status

    The response should be 1.

  5. If this was the first FHIR Interoperability Adapter created for the namespace, navigate to Interoperability > List > Productions, open your production, and do one of the following:

    • If you see an Update button, select it.

    • If the Update button does not appear and you are ready to test your production, select Start to start the production.

Adapter Components

Installing the FHIR Interoperability Adapter creates:

  • A web application with the specified URL

  • A new business service in the interoperability production called InteropService. If you install multiple Adapters, they all use the same InteropService business service. If you want an Adapter to use a different business service, see Using a Custom Business Service.

  • A new business operation in the interoperability production called InteropOperation. This is a placeholder business operation that can be extended or replaced according to your use case. Until you modify InteropOperation to implement custom functionality, it returns an 501 Unimplemented error when a FHIR request is received by the new interoperability REST endpoint.


    When using a production, you must explicitly set the ContentTypeOpens in a new tab property of an HS.FHIRServer.Interop.ResponseOpens in a new tab to create the HTTP response Content-Type header. Setting the ResponseFormatCode in the HS.FHIRServer.API.Data.ResponseOpens in a new tab is not sufficient.

For details about other production components that can be used in conjunction with the FHIR Interoperability Adapter, see Interoperability Productions.

Using a Custom Business Service

By default, if you install multiple FHIR Interoperability Adapters, they all share the same business service, InteropService. If you want requests received by the adapter endpoints to be routed to different business services, you need to create a subclass of the REST handler and specify it as the Dispatch Class of the Adapter’s CSP application. This process of using a custom business service consists of the following steps:

  1. Using an IDE, create a subclass of HS.FHIRServer.HC.FHIRInteropAdapterOpens in a new tab.

  2. Use your subclass’ ServiceConfigName parameter to specify the name of the custom business service that will receive the FHIR requests.

  3. In the Management Portal, navigate to System Administration > Security > Applications > Web Applications.

  4. Select the URL of your FHIR Interoperability Adapter.

  5. Using the Enable field on the General tab, specify the name of your subclass in the Dispatch text box.

  6. Select Save.


Security of the interoperability REST endpoint depends on the security settings of the web application created for the FHIR Interoperability Adapter. For example, you can configure the web application to require that the user making the FHIR request have privileges to an InterSystems resource. The security settings for the web application are available by navigating to System Administration > Security > Applications > Web Applications. The web application is identified by the URL of the interoperability REST endpoint. For details about the security settings, see Edit a Web Application.

The FHIR Interoperability Adapter does not provide extensive OAuth 2.0 support. If a request to the adapter contains an OAuth 2.0 token, it is examined with basic tests that determine if the token is in the Authorization header, is non-blank, and is on a secure connection. Unlike a FHIR server, it does not examine the token’s contents like scope and patient context value. If the token passes the adapter’s basic tests, it is added to the request message in the AdditionalInfo property of HS.FHIRServer.API.Data.RequestOpens in a new tab.

FeedbackOpens in a new tab