Section

  • FHIR R4 Integration QuickStart

    InterSystems IRIS for Health™ helps you build your FHIR® applications quickly and seamlessly.

    Through the use of FHIR and InterSystems IRIS for Health, you can easily:

    • Expose discrete resources, improving performance.
    • Convert data between FHIR and many other healthcare data formats such as HL7 v2 or CDA.
    • Route, transform, and orchestrate data between multiple disparate applications.
    • Store FHIR resources in a FHIR resource repository using InterSystems IRIS for Health as your FHIR application development environment.

    Watch the video or try the exercise below!

    Note: This QuickStart is only applicable for InterSystems IRIS for Health 2020.2+. For 2020.1 and earlier, see the FHIR STU3 Integration QuickStart.
    • Using InterSystems IRIS for Health, within a single platform you can easily:

      • Retrieve or send small, discrete units of data known as FHIR resources.
      • Integrate applications that use different healthcare standards, such as FHIR and HL7 v2.
      • Store data to a FHIR resource repository.
      • Transform data for downstream systems.
      In this exercise, you will load a sample integration solution that consumes healthcare data — both FHIR resources and HL7 v2 messages — and stores it to a FHIR repository within InterSystems IRIS for Health. You will then retrieve small discrete FHIR resources such as a patient or a medication, allowing you to optimize your application to work with just the data you need.

      1.Set up

      Verify you have an instance of InterSystems IRIS for Health and a REST client (such as Chrome Advanced REST client). Then complete the following steps to create a FHIR namespace and load the sample FHIR integration solution into InterSystems IRIS for Health:
      1. Clone this repository: git clone https://github.com/intersystems/samples-integration-FHIR.
      2. Create a new IRIS for Health namespace called FHIRServer. In the InterSystems IRIS Terminal, type:
        • set $namespace = "HSLIB"
        • do ##class(HS.HC.Util.Installer).InstallFoundation("FHIRServer")
      3. From the Management Portal[?] homepage, switch to the FHIRSERVER namespace and navigate to Health > FHIR Configuration > Server Configuration to create a FHIR R4 server endpoint that stores FHIR data as JSON in a FHIR resource repository. Click the plus sign (+) and enter the following settings:
        • metadata: HL7v40
        • interaction strategy: FHIRServer.Storage.Json.InteractionsStrategy
        • URL: /csp/healthshare/fhirserver/fhir/r4
      4. Click the /csp/healthshare/fhirserver/fhir/r4 endpoint you just created, and set the Service Config Name to HS.FHIRServer.Interop.Service. Select Allow Unauthenticated Access and click Update.

        Service Config Name filled in and Allow Unauthenticated Access checked.

      5. In the Management Portal, navigate to System Explorer> Classes. Select FHIRServer as the namespace on the left and import the sample production from <YourRepoHome>/R4/data/FHIRR4Production.xml.
      6. Again in the Management Portal, switch to the FHIRServer namespace and update the location in which the integration looks for new files by going to Interoperability >Configure > Production. Select the EnsLib.HL7.Service.FileService component. Then, on the right, click the Settings tab and change the FilePath to <YourRepoHome>/R4/data/In. Click Apply to save the changes. Click Start to run the production.
      7. Now we will load sample data from patient Kris Herman into the FHIR server. In the InterSystems IRIS Terminal, type:
        • set $namespace = "FHIRSERVER"
        • set sc = ##class(HS.FHIRServer.Tools.DataLoader).SubmitResourceFiles("<YourRepoHome>/R4/data/fhir_json_data","FHIRServer", "/csp/healthshare/fhirserver/fhir/r4")
        • write sc

      You now have a FHIR integration solution that handles both FHIR and HL7 v2 messages and stores all data to a FHIR repository. In the next several steps, you will walk through and explore this solution.

      2.Retrieve discrete FHIR resources easily, optimizing speed and performance

      FHIR resources are especially useful for low-bandwidth situations, such as on mobile devices. Other healthcare standards often send more data than is needed. Using FHIR with InterSystems IRIS for Health, you can retrieve a single resource, such as a patient, medication, or observation. InterSystems IRIS for Health includes a flexible base implementation of a FHIR server that conforms to the official FHIR specification. See an example in the next several steps.
      1. Go to the Advanced REST Client (or a similar REST client) and get patient Kris Harmen using the following values:

      2. Headers:
        • Accept: application/fhir+json
        • Content-type: application/fhir+json
        HTTP Request: GET http://YourIP:YourPort/csp/healthshare/fhirserver/fhir/r4/Patient?family=Herman&given=Kris

        Note: Remember to replace YourIP and YourPort with the IP and web server port of your InterSystems IRIS instance. Need help finding these?
      3. From the result in the previous step, you can see patient Kris Herman's ID is 15. You can get any other information about him, including related resources such as AllergyIntolerance and Encounter, by adding $everything to the end of your URL:

        HTTP Request: GET http://YourIP:YourPort/csp/healthshare/fhirserver/fhir/r4/Patient/15/$everything

      3.Easily store FHIR resources centrally, using InterSystems IRIS for Health as your FHIR application development environment

      In the previous section, you queried data that was already stored to the InterSystems IRIS for Health FHIR repository. Let’s see how easy it is to consume FHIR data, store it to the FHIR repository, and retrieve it again. 
      1. Using your REST client, use the following HTTP request to store a new AllergyIntolerance resource:

        HTTP Request: POST http://YourIP:YourPort/csp/healthshare/fhirserver/fhir/r4/AllergyIntolerance

        Body: Copy the example from the FHIR website here: http://hl7.org/fhir/allergyintolerance-medication.json.html

        If successful, you should get a 201 Created message.

      2. Retrieve the Allergy resource with high criticality you just stored to the FHIR repository:

        HTTP Request: GET http://YourIP:YourPort/csp/healthshare/fhirserver/fhir/r4/AllergyIntolerance?criticality=high 

      4Use integration tools to easily convert between FHIR and legacy HL7 v2 applications

      Need to expose your data as FHIR? Using InterSystems IRIS for Health, HL7 v2 data can be consumed, converted to FHIR, and stored in a FHIR repository or sent to other FHIR applications. In this step, you will consume an ADT_A01 HL7 v2 message, store it to the FHIR repository, and then use REST to query for the FHIR resource.

      HL7 v2 data is consumed, converted to FHIR, and stored in a FHIR repository as specified.


      1. Copy the ADT_A01.txt file, with information about the patient Jane Carter, located in <YourRepoHome>/R4/data/SampleFiles, to the <YourRepoHome>/R4/data/In folder. InterSystems IRIS for Health will consume this file, convert the contents to FHIR resources, and store the data to the FHIR repository.
      2. Using the REST client again, search for Jane's resource:
        GET http://YourIP:YourPort/csp/healthshare/fhirserver/fhir/r4/Patient?family=Carter
      3. All messages sent through InterSystems IRIS for Health are stored to an internal database, making it easy to track, follow, and troubleshoot messages.
        1. Open the Management Portal and go to Interoperability > View > Messages. Choose the message with Source equal to EnsLib.HL7.Service.FileService.
        2. Click Trace on the right, then click View Full Trace. This view shows how messages traverse the integration solution at every step. Notice that the EnsLib.HL7.Service.FileService service consumed the file and is the starting point for this trace. It then sends the HL7 input message to the Demo.FHIRHL7ToFHIRRequestBPL process, which uses a BPL to extract Patient MRN from the incoming message and to subsequently transform the HL7 message into a bundle of FHIR resources (via HS.FHIR.DTL.Util.HC.SDA3.FHIR.Process), using the Patient MRN as the patient resource ID. Then, the transformed output is sent to HS.FHIR.Interop.Operations, which internally stores the FHIR resources in the FHIR repository.
        3. Select the first Request message between HS.FHIRServer.Interop.Operation and HS.Util.Trace.Operations. The HS.Util.Trace.Operations component allows you to display the actual contents of the FHIR message in the Contents pane on the right. Can you find the given name of the patient?

          Request message is chosen and Content tab is displayed as specified.

        4. Going back to message list, you can see there is a message with Source equal to HS.FHIRServer.Interop.Service. This is because during initial setup, the FHIR server endpoint’s Service Config Name setting was set to HS.FHIRServer.Interop.Service, and this optional setting allows all FHIR REST messages (such as FHIR search requests) to flow through an interoperability production before reaching the internal FHIR server core.