• FHIR STU3 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 applicable to InterSystems IRIS for Health 2020.1 and earlier. For 2020.2+, see the FHIR R4 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 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

      1. Verify you have an instance of InterSystems IRIS for Health and a REST client (such as Chrome Advanced REST client). The easiest way to try this sample is to use InterSystems IRIS for Health Learning Labs which includes a built-in IDE. If you are using AWS, Azure, or GCP, verify that you have followed the steps to change the password for InterSystems IRIS.

      2. Create a FHIR namespace and load the sample FHIR integration solution into InterSystems IRIS for Health:

      3. Learning Labs, Evaluation Edition

        The sample FHIR integration solution is already loaded. You can skip to the next step.

        AWS, GCP, Azure Community Edition
        Type: iris load
        Local instance
        1. Clone or download this repository: .This repository has a folder named data, which contains all files needed to load the sample integration solution as well as folders that contain the sample HL7 v2 messages.
        2. Create a new FHIR namespace with the standard FHIR STU3 production. To do this, in Terminal type:
          zn "HSLIB"
          do ##class(HS.HC.Util.Installer.FHIR).Install()
          Namespace : FHIRNamespace
          Install DSTU2? (Y/N) N
          Install STU3? (Y/N) Y
          STU3 CSP App <Press Enter to accept default>
          STU3 CSP Open ID Connect (OAuth 2.0) app <Press Enter to accept default>
          Install STU3 resource repository? (Y/N) Y
          Install STU3 PIXm (Y/N) N
          Install STU3 PDQm? (Y/N) N
          Install STU3 MHD? (Y/N) N
          Continue with Installation? (Y/N) Y

        3. In the Management Portal, navigate to System Explorer > Classes. Select FHIRNamespace as the namespace on the left and import the sample production from /STU3/data/FHIRNamespaceProduction.xml .
        4. Again in the Management Portal, update the location in which the integration looks for new files by going to Interoperability > Configure > Production. Select the From_ADT component. Then, on the right, click the Settings tab and modify the following settings:
          • FilePath: <YourRepoHome>/STU3/data/In
          • ArchivePath: <YourRepoHome>/STU3/data/Out
          Click Apply to save the changes.

      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.Send discrete FHIR resources to make them easy to retrieve, 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. However, using FHIR with InterSystems IRIS for Health you can simply send one 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 1 using the following values:
        HTTP Request: GET http://YourIP:YourPort/csp/healthshare/fhirnamespace/fhir/stu3/Patient/1   

        Note: Remember to replace YourIP and YourPort with the IP and web server port of your InterSystems IRIS instance. Need help finding these?

        • Authorization: SuperUser/SYS (or other credentials that work for your InterSystems IRIS for Health instance)
        • Accept: application/fhir+json
        • Content-type: application/fhir+json;charset=utf-8
      2. You can also get all information about Patient 1, including related resources such as AllergyIntolerance and Encounter, using $everything. Add this to the end of your url.
        GET http://YourIP:YourPort/csp/healthshare/fhirnamespace/fhir/stu3/Patient/1/$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/fhirnamespace/fhir/stu3/AllergyIntolerance
        Body: Copy the example from the FHIR website here:

        If successful, you should get a 201 Created message.

      2. Retrieve the resource you just stored to the FHIR repository:
        HTTP Request: GET http://YourIP:YourPort/csp/healthshare/fhirnamespace/fhir/stu3/AllergyIntolerance/2

        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.

        FHIR Integration

        1. Copy the ADT_A01.txt file, located in  <repo home>/STU3/data/SampleFiles to the <repo home>/STU3/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.

          Learning Labs
          1. Open the provided learning IDE, which has a mapped folder between the provided IDE and InterSystems IRIS for Health named shared.
          2. Copy and paste home/project/shared/samples-integration-FHIR/SampleFiles/ADT_A01Carter.txt to the home/project/shared/samples-integration-FHIR/In folder.

          AWS, GCP, Azure
          1. SSH to the node.
          2. Navigate to the bash shell: sudo docker exec -it try-iris bash .
          3. Copy the sample ADT_A01.txt file to the in folder: cp /home/project/shared/samples-integration-FHIR/STU3/data/SampleFiles/ADT_A01Carter.txt /home/project/shared/samples-integration-FHIR/STU3/data/In
          Local instance
          1. Copy and paste the <repo home>/STU3/data/SampleFiles/ADT_A01Carter.txt file to the <repo home>/STU3/data/In folder.
          If you open the HL7 v2 message from the SampleFiles folder, you will notice the message contains information about the patient Jane Carter. Using the REST client again, you can search for the resource for Jane.
        1. GET http://YourIP:YourPort/csp/healthshare/fhirnamespace/fhir/stu3/Patient?family=Carter

        2. All messages that are sent through InterSystems IRIS for Health are stored to an internal database, making it easy for you to track, follow, and troubleshoot messages.
          1. Open the Management Portal [?] (if you have the built-in IDE, you can use the menu at the top to click InterSystems > InterSystems IRIS Management Portal) and go to Interoperability > View > Messages. The top message with Source equal to HS.FHIR.Service.STU3 contains information about the previous request for the AllergyIntolerance resource.
          2. Click Trace on the right, then click View Full Trace. This view shows how messages traverse the integration solution at every step. You should notice that the HS.FHIR.Service.STU3 service consumed the file and is the starting point for this trace. It then sends a message to the HS.FHIR.Server.Process.STU3 process, which then sends a message to the HS.FHIR.Repository.Operations.STU3 operation.
          3. Select the Request message between HS.FHIR.Repository.Operation.STU3 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?

        5(Optional) Built-in data transformations allow you to easily modify data with no code

        InterSystems IRIS for Health supports the ability to modify contents of a message, as needed, for downstream systems. These are called data transformations. Each FHIR resource has its own transformation within InterSystems IRIS for Health. To customize one of the data transformations, you open an existing transformation, save it in the HS.Local folder so that upgrades do not overwrite your customizations, and make any changes you need to make. Here you will check if the address is 1 Memorial Drive and, if so, add InterSystems! to the Text field of the address.
        1. Copy the standard transformation and create a new transformation with customizations.
          1. Navigate to the Data Transformation Editor in the Management Portal by opening Interoperability > List > Data Transformations.
          2. Open HS.FHIR.DTL.SDA3.vSTU3.Address.Address.
          3. Click Save As and specify HS.Local.FHIR.DTL.SDA3.vSTU3.Address as the package and Address as the name.
          Note: You now have the base data transformation for Address. Data has already been converted from HL7 v2 to SDA, the internal data format available to easily convert between all healthcare standards within InterSystems IRIS for Health. While using this internal format is not required, it allows you to easily use existing pieces to speed up your development process. The transformation then converts data from SDA to FHIR.

        2. Add in your customizations.
          1. On the left under Source, click Street and select Add Action > if. On the right under Action, add to the condition so it says: source.Street = “1 Memorial Drive”
          2. In the middle under Target, click Text and select Add Action > set. For Value, type "InterSystems!"
          3. Click Compile.
        3. Again copy and paste ADT_A01Carter.txt from <repo home>/STU3/data/SampleFiles to the <repo home>/STU3/data/In folder.

        4. Using the REST Client, search for Carter again. Notice you now have two resources for Jane Carter. The second resource will include a text field equal to “InterSystems!”.

          Problems? In the InterSystems Terminal, update the default package local by typing:
          zn "FHIRNamespace"
          set status = ##class(HS.FHIR.DTL.Util.API.ExecDefinition).SetCustomDTLPackage("HS.Local.FHIR.DTL")