InterSystems healthcare products provide built-in business hosts that you can use to create an interoperability production that accepts and/or sends out FHIR® requests. For example, there is a business service that takes in FHIR requests from the REST handler of an InterSystems FHIR endpoint. If you are unfamiliar with interoperability productions, see Introduction to Interoperability Productions.
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.
Accepting FHIR Requests
The built-in business service HS.FHIRServer.Interop.Service is designed to receive FHIR requests that have been sent to the endpoint that was created when you installed a FHIR server. Once configured, the endpoint’s REST handler routes the request to HS.FHIRServer.Interop.Service rather than the FHIR server’s Service. You need to install a FHIR server endpoint even if the FHIR request never reaches the InterSystems FHIR server’s architecture, as is the case when the production’s business operation forwards the request to an external system or the FHIR request is transformed into a different healthcare format.
Setting up an endpoint to route FHIR requests through an interoperability production is a two-step process:
Create an interoperability production and add the HS.FHIRServer.Interop.Service 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.
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.Service 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.
Configuring the Endpoint
After installing a FHIR server endpoint, the endpoint can be configured to use an interoperability production at anytime, 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:
In the Management Portal, navigate to Health > FHIR Configuration > Server Configuration. Make sure you are in the FHIR server’s namespace.
Select the endpoint.
In the Service Config Name field of the Interoperability section, specify 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
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 to a FHIR server:
|Business Operation Class||Description|
|HS.FHIRServer.Interop.Operation||Sends a FHIR request to the internal Service of an InterSystems FHIR server in the local namespace.
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.Process), the server is identified by the FHIREndpoint setting of the business process.
|HS.FHIRServer.Interop.HTTPOperation||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.Service) sends a request message (HS.FHIRServer.Interop.Request) to the HS.FHIRServer.Interop.HTTPOperation 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.HTTPOperation, 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.Interop, 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.Process, the FHIR forwarded from this business process to HS.FHIRServer.Interop.HTTPOperation 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( ) 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.HTTPOperation business operation.
pTargetConfigName — Name of the HS.FHIRServer.Interop.HTTPOperation 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( ) 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.Interop) 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.BusinessService business service must be added to the production along with HS.FHIRServer.Interop.HTTPOperation. Instantiating the client is similar, but for standalone applications, the call to CreateInstance should not include an argument for the pHostObj parameter.
The message class used to pass FHIR requests within the production is HS.FHIRServer.Interop.Request.
The message class used to pass a response from the FHIR server back through the production to the FHIR client is HS.FHIRServer.Interop.Response.
These classes include a property QuickStreamId that points to the FHIR payload. For information about working with a FHIR payload in JSON format, see Accessing FHIR Payloads in Production-Based Implementations.
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. To use the transformations, you must use the Installer Wizard to create a Foundation namespace, and then add the business process to the production that was created automatically when the namespace was created. No other production can be used.
For more information about SDA-FHIR transformations using the built-in business processes, see Transformation Business Processes.
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 an InterSystems FHIR server to create an endpoint. Even if your proxy server forwards the request to an external FHIR endpoint without accessing an internal InterSystems FHIR server, you still need to install the FHIR server to create the endpoint.
Setting up the InterSystems endpoint to forward requests to HS.FHIRServer.Interop.Service. For more information, see Accepting FHIR Requests.
Adding HS.FHIRServer.Interop.HTTPOperation to the production and editing the ServiceName setting to specify the external FHIR endpoint.
Editing the TargetConfigName of HS.FHIRServer.Interop.Service to point to HS.FHIRServer.Interop.HTTPOperation.
Of course, there are variations on the proxy server use case. For example, you could also add multiple HS.FHIRServer.Interop.HTTPOperation business operations and use a business process to determine which external FHIR endpoint should be the target of the proxy server. You could even add HS.FHIRServer.Interop.Operation to the production and have the proxy server store FHIR data in the internal InterSystems FHIR server along with sending it out to an external FHIR endpoint.
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.HTTPService.
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)Copy code to clipboard
For more information about this transformation method, see Data Transformations in InterSystems Healthcare Products.
Adding the HS.FHIR.DTL.Util.HC.SDA3.FHIR.Process 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.Process.
Once the HL7 data has been transformed into FHIR, it can be sent to an external FHIR endpoint or, in the case of InterSystems IRIS for Health, stored in an internal Resource Repository of the FHIR server. 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.Process 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 QuickStart.
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, then adding HS.FHIRServer.Interop.Operation as described in Sending FHIR Requests. Once both business hosts are added to the production, modify the TargetConfigName setting of HS.FHIRServer.Interop.Service to specify the name of the HS.FHIRServer.Interop.Operation 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.