Interoperability Productions for FHIR
InterSystems healthcare products provide built-in business hosts that you can use to create an interoperability production that accepts and/or sends out HL7® FHIR® requests. Business processes that transform SDA to FHIR and FHIR to SDA are also available.
To explore some of the FHIR implementations that are possible using an interoperability production, see Use Cases.
The InterSystems FHIR server does not require an interoperability production; by default, FHIR requests received by an endpoint’s REST handler are sent directly to the FHIR server’s Service. FHIR servers that do not use an interoperability production can be significantly faster.
Accepting FHIR Requests
FHIR implementations can accept FHIR requests into an interoperability production is two ways:
-
For FHIR servers (implementations that leverage the internal architecture and storage of an InterSystems product), the FHIR request can be sent through HS.FHIRServer.Interop.ServiceOpens in a new tab on its way to the repository. For details, see Accepting FHIR Server Requests.
-
For implementations that do not use a FHIR server, you can use the FHIR Adapter for Interoperability Productions to accept FHIR requests into an interoperability production. For details, see FHIR Adapter for Interoperability Productions.
Security for Incoming Requests
A FHIR request can enter an interoperability production using a FHIR Adapter for Interoperability Productions or a FHIR Server that uses a production. Security is handled differently depending on which feature you are using to receive the request. If your production is using the FHIR interoperability, see Adapter Security. If your production is using a FHIR server, see Server Security
Accepting FHIR Server Requests
The built-in business service HS.FHIRServer.Interop.ServiceOpens in a new tab is designed to receive FHIR requests that have been sent to a FHIR server endpoint. Once configured, the endpoint’s REST handler routes the request to HS.FHIRServer.Interop.ServiceOpens in a new tab rather than the FHIR server’s Service.
Setting up an endpoint to route FHIR server requests through an interoperability production is a two-step process:
-
Create an interoperability production and add the HS.FHIRServer.Interop.ServiceOpens in a new tab business service.
-
Configure an endpoint’s Service Config Name field so it specifies the name of the business service that has been added to the interoperability production.
These steps can be taken in any order as long as, when the setup is complete, the name of the business service in the endpoint’s configuration matches the name in the interoperability production.
This two-step process assumes you are using a FHIR server; if your implementation does not leverage the internal architecture and repository of a FHIR server, use the FHIR Adapter for Interoperability Productions to accept FHIR requests.
Creating the Interoperability Production
When the Foundation namespace for the FHIR server endpoint is created, the installation process also creates an interoperability production that should be used as the FHIR production. You need to modify the production to add the required business service that the endpoint uses to route requests through the production.
Interoperability productions that receive FHIR requests from the REST handler must include the HS.FHIRServer.Interop.ServiceOpens in a new tab business service. You can give the business service a custom name, but make sure that name matches the one specified for the endpoint’s Service Config Name option. For details, see Adding Business HostsOpens in a new tab.
Configuring the Endpoint
After installing a FHIR server endpoint, the endpoint can be configured to use an interoperability production at any time, including before the production has been created. Specifying the name of the business service while configuring the endpoint does not automatically create the business service in your production.
To configure an existing endpoint so FHIR requests are routed through a production:
-
Navigate to Health > MyNamespace > FHIR Server Management.
-
In the tile for the desired endpoint, choose Edit from the menu.
-
In the Advanced Configuration section, from the Service Config Name dropdown, choose the name of the business service of the production through which FHIR requests will be routed. For example, if the business service does not have a custom name, specify HS.FHIRServer.Interop.Service
-
Click Save.
Sending FHIR Requests
Within an interoperability production, business operations are responsible for making sure a FHIR request is sent to a FHIR endpoint. This request can originate from a variety of sources, for example, from an external FHIR client accessing an InterSystems endpoint or from a business process that transforms HL7 messages into FHIR requests. Regardless of its origin, there are two business operations available to send requests:
Business Operation Class | Description |
---|---|
HS.FHIRServer.Interop.OperationOpens in a new tab | Sends a FHIR request to the internal Service of an InterSystems FHIR server in the local namespace. Except in rare cases where a custom architecture has been implemented, Health Connect users cannot use this business operation unless they have a license to use the Resource Repository.
This business operation identifies the correct InterSystems FHIR server based on the URL of its endpoint, which is included in the SessionApplication property of the request message. If the message originated from a request sent to the FHIR server’s endpoint through the REST Handler, the endpoint’s URL is already part of the message. If the message was sent from the business process that transforms SDA to FHIR (HS.FHIR.DTL.Util.HC.SDA3.FHIR.ProcessOpens in a new tab), the server is identified by the FHIREndpoint setting of the business process. |
HS.FHIRServer.Interop.HTTPOperationOpens in a new tab | Sends a FHIR request to an internal or external FHIR endpoint over HTTP.
If you are using a built-in business host to send the request to this business operation, use that business host’s TargetConfigName setting. The default HTTP address of the FHIR endpoint is specified with the business operation’s ServiceName setting, which refers to an entry in the Service Registry. This default is overridden if a request includes an AdditionalInfo item named ServiceName, which specifies a Service Registry entry pointing to the alternate endpoint. |
If a built-in business host (such as HS.FHIRServer.Interop.ServiceOpens in a new tab) sends a request message (HS.FHIRServer.Interop.RequestOpens in a new tab) to the HS.FHIRServer.Interop.HTTPOperationOpens in a new tab business operation, the request is sent over HTTP without custom code. However, if a FHIR payload is formulated within a custom business host that needs to put the payload into a FHIR request, you should instantiate an interoperability FHIR client to send the message. Similarly, if your custom business host needs to retrieve FHIR data from an endpoint, your production should use the FHIR client.
Interoperability FHIR Client
InterSystems technology provides a FHIR client object that simplifies the process of formulating a FHIR request from within a custom business host and sending it to a FHIR endpoint over HTTP. The business operation, HS.FHIRServer.Interop.HTTPOperationOpens in a new tab, that is used by the FHIR client to send the request over HTTP must be added to the interoperability production. Once the production is configured, your custom business host can use the FHIR client by instantiating HS.FHIRServer.RestClient.InteropOpens in a new tab, then calling the methods that correspond to FHIR interactions and operations.
Not all productions that send out FHIR requests over HTTP need to instantiate the interoperability FHIR client. For example, if SDA is being transformed into FHIR using HS.FHIR.DTL.Util.HC.SDA3.FHIR.ProcessOpens in a new tab, the FHIR forwarded from this business process to HS.FHIRServer.Interop.HTTPOperationOpens in a new tab is sent out via HTTP without the FHIR client. However, when a FHIR payload is formulated by a custom business host within a production, the recommended method of sending it to a FHIR endpoint over HTTP is to instantiate the FHIR client.
When instantiating the FHIR client within the context of a custom business host, the call to the CreateInstance( )Opens in a new tab method must contain the following parameters:
-
pServiceName — Name of an entry in the Service Registry that points to a FHIR endpoint. This value overrides the ServiceName setting of the HS.FHIRServer.Interop.HTTPOperationOpens in a new tab business operation.
-
pTargetConfigName — Name of the HS.FHIRServer.Interop.HTTPOperationOpens in a new tab business operation.
-
pHostObj — Object instance of the business host that is instantiating the FHIR client. You can use $this to specify the current business host object that is instantiating the FHIR client.
For example, to instantiate a FHIR client within a business host with only the required arguments, enter:
Set fhirClient = ##class(HS.FHIRServer.RestClient.Interop).CreateInstance(
"MyFHIR.HTTP.Service",
, , , , ,
"HS.FHIRServer.Interop.HTTPOperation",
$this)
The CreateInstance( )Opens in a new tab method also accepts optional arguments that specify the value of the FHIR prefer header and send an OAuth token with the request.
Once the FHIR client has been instantiated, you can use it to send requests and perform operations. For details on using the FHIR client’s methods to perform these actions, see Interactions and Operations.
The interoperability FHIR client class (HS.FHIRServer.RestClient.InteropOpens in a new tab) can also be used by a standalone ObjectScript application that needs to send a FHIR request through an interoperability production. In this case, the HS.HC.Util.BusinessServiceOpens in a new tab business service must be added to the production along with HS.FHIRServer.Interop.HTTPOperationOpens in a new tab. Instantiating the client is similar, but for standalone applications, the call to CreateInstance() should not include an argument for the pHostObj parameter.
Transformations
You can add built-in business processes to your production to invoke SDA-FHIR transformations. For example, a production could consume HL7 messages, use a business process to convert the HL7 to SDA, and then use the built-in SDA-FHIR business process to convert the SDA to FHIR. The production running these transformations must be in a Foundation namespace.
For more information about SDA-FHIR transformations using the built-in business processes, see Transformation Business Processes.
Use Cases
The following use cases provide examples of how to use the built-in interoperability components to work with FHIR resources.
InterSystems healthcare products can be used as a proxy server that accepts FHIR requests from an external FHIR client and forwards them to an external FHIR endpoint, then routes responses from the FHIR endpoint back to the external client. In this scenario, the FHIR client might be unaware that the InterSystems product is not the server that is accepting and producing FHIR, and the request or response can be manipulated within the production as needed.
You could implement a simple proxy server by:
-
Installing the FHIR Adapter for Interoperability Productions.
-
Adding HS.FHIRServer.Interop.HTTPOperationOpens in a new tab to the production and editing the ServiceName setting to specify the external FHIR endpoint.
-
Editing the TargetConfigName of InteropService to point to HS.FHIRServer.Interop.HTTPOperationOpens in a new tab.
Of course, there are variations on the proxy server use case. For example, you could also add multiple HS.FHIRServer.Interop.HTTPOperationOpens in a new tab business operations and use a business process to determine which external FHIR endpoint should be the target of the proxy server.
If you wanted to store FHIR data in an internal InterSystems repository along with sending it out to an external FHIR endpoint, you would need to start with a FHIR Server rather than the FHIR Adapter for Interoperability Productions. In this case, you could send requests to external endpoints using HS.FHIRServer.Interop.HTTPOperationOpens in a new tab, but also use HS.FHIRServer.Interop.OperationOpens in a new tab to store the data internally.
InterSystems healthcare products simplify the process of extracting clinical data from incoming HL7 messages and transforming that data into FHIR resources. Once transformed into FHIR, the clinical data can be forwarded to external FHIR endpoints or stored in an internal FHIR repository that can be queried by FHIR clients. A basic interoperability production that transforms HL7 messages into FHIR resources would include:
-
Adding a built-in business service that accepts HL7 messages into the production, for example, EnsLib.HL7.Service.HTTPServiceOpens in a new tab.
-
Using a business host to transform the HL7 into SDA (the InterSystems intermediary data format). The following code added to a business process is enough to transform the HL7 into SDA:
do ##class(HS.Gateway.HL7.HL7ToSDA3).GetSDA(request,.con) set streamContainer = ##class(ENS.StreamContainer).%New() set streamContainer.Stream = con set sc = ..SendRequestSync("SDAToFHIRProcess",streamContainer,.pResponse)
For more information about this transformation method, see Data Transformations in InterSystems Healthcare Products.
-
Adding the HS.FHIR.DTL.Util.HC.SDA3.FHIR.ProcessOpens in a new tab business process to the production; this business process transforms SDA into FHIR.
-
Modifying the TargetConfigName setting of the business host that contains the HL7–to-SDA transformation method to specify the name of HS.FHIR.DTL.Util.HC.SDA3.FHIR.ProcessOpens in a new tab.
Once the HL7 data has been transformed into FHIR, it can be sent to an external FHIR endpoint or, in the case of FHIR server, stored in an internal Resource Repository. You control where the FHIR data is forwarded by adding a business operation that performs a specific function. For details about these business operations, see Sending FHIR Requests. If you are using the business operation that forwards requests to the internal storage of the FHIR server, use the FHIREndpoint setting of HS.FHIR.DTL.Util.HC.SDA3.FHIR.ProcessOpens in a new tab to specify the InterSystems FHIR server’s endpoint.
For a hands-on example of integrating HL7 message with a FHIR server, see FHIR R4 Integration QuickStartOpens in a new tab.
By default, requests to an InterSystems FHIR server do not go through an interoperability production, however you may want to use a production in some cases. For example, you may want to use a production during development to leverage message tracing and other advantages of productions, then make a small modification to send requests directly to the server’s Service when it goes live. In an alternate use case, you might want to manipulate the FHIR requests using a business process before they reach the InterSystems FHIR server.
In its simplest form, a production-based FHIR server consists of configuring the production as described in Accepting FHIR Server Requests, then adding HS.FHIRServer.Interop.OperationOpens in a new tab as described in Sending FHIR Requests. Once both business hosts are added to the production, modify the TargetConfigName setting of HS.FHIRServer.Interop.ServiceOpens in a new tab to specify the name of the HS.FHIRServer.Interop.OperationOpens in a new tab business operation.
If your aim is to use a production during development, then switch to a FHIR server that sends a request directly to the Service, simply reconfigure the Server’s endpoint by removing the value in the Service Config Name field when the server goes live.