Topic outline

• Importing FHIR Packages into the InterSystems IRIS for Health Server

  Importing FHIR Packages into the InterSystems IRIS for Health Server

  HL7® FHIR® packages are collections of resources that can be distributed under one name. With a FHIR package, there is no need to version individual resources or update cascading profiles. They facilitate automated publication, discovery, consumption, and updates. FHIR packages are closely related to FHIR profiles, since FHIR packages may contain customized resources. A FHIR profile is a customized specific resource definition, created by specifying a set of constraints and/or extensions on a base FHIR resource.

  InterSystems IRIS for Health™ helps you work with FHIR packages and FHIR profiles quickly and seamlessly. The exercise below helps you understand how to work with FHIR packages in InterSystems IRIS for Health. Specifically, you will learn how to:

  • Configure the FHIR server in InterSystems IRIS for Health, which is capable of supporting multiple FHIR packages.
  • Identify basic structure of a FHIR package.
  • Import an existing, published FHIR package into the InterSystems IRIS for Health FHIR server.
  • Import a custom FHIR package into the InterSystems IRIS for Health FHIR server.

  Note: This exercise is applicable to InterSystems IRIS for Health 2020.4+.
• Collapse allExpand all
  Try It

  Try It

  In this exercise, you will find and import published FHIR packages into InterSystems IRIS for Health. You will also use a sample custom FHIR package to search for FHIR resources based on a custom search parameter.

  • You must be logged in to launch an InterSystems IRIS instance.

    • Log in with your existing account.
    • Don't have an InterSystems account? Create a new account.
  • Create a FHIR endpoint
    

    Verify you have launched the learning lab above and and have 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. See this overview of the Management Portal if needed.

    1. From the Management Portal homepage, switch to the FHIRSERVER namespace and navigate to Health > FHIR Configuration > Server Configuration.
    2. Add a FHIR endpoint:
       1. Click Add Endpoint.
       2. Under Core FHIR package, select hl7.fhir.r4.core@4.0.1.
       3. Under Additional Packages (optional), select hl7.fhir.us.core@3.1.0.
       4. Click Add.

       Note: It will take a few minutes for the endpoint to be created.

    3. Click the /csp/healthshare/fhirserver/fhir/r4 endpoint you just created, and click Edit.
    4. Select Allow Unauthenticated Access, and click Update.

    You now have created a FHIR endpoint in the InterSystems IRIS for Health FHIR server. In the next section, you will post FHIR resources to this server and retrieve resources from the server.

  • Post resources to the FHIR server
    

    Now that you have a FHIR server set up, you can post resources to the FHIR repository. In this example, you will post a Medication Knowledge resource into the FHIR server.

    1. To post the Medication Knowledge resource, open your REST client and fill in the following values:
       Headers:
       • Accept: application/fhir+json
         
       • Content-Type: application/fhir+json
         
       HTTP Request: POST http://Host Server Address/csp/healthshare/fhirserver/fhir/r4/MedicationKnowledge.
       Replace Host Server Address with the value of the Host Server Address value in your learning lab, for example: 52773-1-e0410394.labs.learning.intersystems.com.
       
       Body: Copy from this JSON file. If POST is successful, you will see the status 201 Created. If you do not see this status, double-check your Host Server Address.
    
    
    2. Try to retrieve the resource you just stored to the FHIR repository by modifying the HTTP request to:
       GET http://Host Server Address/csp/healthshare/fhirserver/fhir/r4/MedicationKnowledge?DrugPlan=4030MyPlan

    You will encounter the error ParameterNotSupported because DrugPlan is not a search parameter in the base FHIR specification. This parameter is unique to the DaVinci Drug Formulary package, which is currently not in the FHIR server. You will download and import the DaVinci Drug Formulary package containing this parameter to the FHIR server, enabling you to search for patients based on their drug plan.

    The next section explains how to download the published DaVinci package.

  • Download published FHIR packages
    

    A FHIR package is a collection of FHIR profiles and other conformance resources, such as ValueSet and SearchParameters. To use these types of conformance resources, download FHIR packages that contain them. FHIR packages have unique names such as hl7.fhir.core and can be found on the FHIR Package Registry website. Follow these steps to download the DaVinci Drug Formulary package containing the DrugPlan search parameter:

    1. Install npm in your local system: https://www.npmjs.com/get-npm.
    2. Go to the FHIR Package Registry website and search for the DaVinci Drug Formulary package.
    3. To install the package in your system:
       1. Copy the command from the registry website, which looks like this: npm --registry https://packages.simplifier.net install hl7.fhir.us.Davinci-drug-formulary@1.0.1.
       2. Paste the command into the Terminal.
    4. FHIR packages evolve frequently, so you might need to update the dependencies to avoid any mismatch between FHIR packages and InterSystems IRIS for Health. Open package.json under your package files, located under the node_modules folder, and update dependencies field to the following:Begin code:

       "dependencies": {
           "hl7.fhir.r4.core": "4.0.1",
           "hl7.fhir.us.core": "3.1.0"
         },
       

       End code.
    5. Open example/SearchParameter-DrugPlan.json in your package files. Notice that this JSON file contains:
       • resourceType: SearchParameter
       • code: DrugPlan
  • Import FHIR packages into the InterSystems IRIS for Health FHIR server
    

    After downloading the DaVinci Drug Formulary package, you will need to import it into the InterSystems IRIS for Health server. To do this, complete the following steps:

    1. From the Management Portal homepage, switch to the FHIRSERVER namespace and navigate to Health > FHIR Configuration > Package Configuration.
    2. Click Import Package > Select Package directory.
    3. Select the hl7.fhir.us.Davinci-drug-formulary folder and click Import.
    4. Add this package to the endpoint:
       1. Go back to the Server Configuration page by clicking the gear button () on the left.
       2. Select /csp/healthshare/fhirserver/fhir/r4 and click Edit.
       3. Select Additional packages as hl7.fhir.us.Davinci-drug-formulary@1.0.0.
       4. Click Update.
       Note: It will take a few minutes for the endpoint to be updated.
    5. Verify that the packages have been imported properly by retrieving the MedicationKnowledge resource again. You should now be able to retrieve the resource.
       GET http://YourIP:YourPort/csp/healthshare/fhirserver/fhir/r4/MedicationKnowledge?DrugPlan=4030MyPlan

    Note:

    If you get an error message, go to InterSystems > Web Terminal and type:

    • set $namespace = "FHIRSERVER"
    • do ##class(HS.FHIRServer.ConsoleSetup).Setup()

    Choose option 8 to index the new Search parameter.
  • Add custom FHIR packages to the FHIR server
    

    In the previous section, you imported a published package from the FHIR Registry website into the FHIR server to search for patients based on their drug plan. Instead of using existing packages, you can use your own custom package if the published packages do not contain the resources you need.

    In this section, you will download a sample custom FHIR package and upload it to the server, then find patients based on their favorite color.

    1. Download and unzip this sample custom FHIR package, which contains:
       • the StructureDefinition for an extension that stores a patient’s favorite color
       • the SearchParameter that searches for values in that extension
    2. Inside the FHIR package you just downloaded, open the package.json file, which is required for any custom package. Notice that the package has some common fields such as name, version, and dependencies: Begin code:

       "name": "isc-demo-package",
       	"version": "0.0.1",
               "dependencies": {
        	"hl7.fhir.r4.core": "4.0.1",
         	"hl7.fhir.us.core": "3.1.0"
               },
       

       End code.
    3. Import the custom package into the FHIR server:
       1. From the Management Portal homepage, switch to the FHIRSERVER namespace and navigate to Health > FHIR Configuration > Package Configuration.
       2. Click Import Package > Select Package directory.
       3. Select the isc-demo-package folder and click Import.
    4. Add this package to the endpoint by going back to the server configuration:
       1. Select /csp/healthshare/fhirserver/fhir/r4 and click Edit.
       2. Select Additional Packages as isc-demo-package@0.0.1.
       3. Click Update.
       Note: It will take a few minutes for the endpoint to be updated.
    5. Load a patient whose favorite color is green into the FHIR server by filling in the following fields in your REST client:
       Headers:
       • Accept: application/fhir+json
         
       HTTP Request: POST http://YourIP:YourPort/csp/healthshare/fhirserver/fhir/r4/Patient
       
       Body: Copy from this JSON file.
    6. Verify that the packages have been imported properly by retrieving a patient who likes the color green:
       GET http://YourIP:YourPort/csp/healthshare/fhirserver/fhir/r4/Patient?FavoriteColor=Green
    Note:
    If you get an error message, go to InterSystems > Web Terminal and type:
    • set $namespace = "FHIRSERVER"
    • do ##class(HS.FHIRServer.ConsoleSetup).Setup()
    Choose option 8 to index the new Search parameter.
    7. (Optional) Are you wondering why custom packages allow you to search for patients who like the color green? Open the following files and look at some of their critical fields:
       • SearchParameter-FavoriteColor.json has the resourceType SearchParameter and code FavoriteColor.
       • StructureDefinition-demo-FavoriteColor-Extension.json has the resourceType StructureDefinition and id patient-FavoriteColor-extension.
       • sample_data.json has the URL http://isc.demo/fhir/StructureDefinition/patient-FavoriteColor-extension and valueString green.

    With FHIR custom packages, you can easily add the resources you want into the FHIR server. Feel free to review the provided custom package and create your own custom package!

• Importing FHIR Packages Demo

  Importing FHIR Packages Demo

  • Watch the following video to see a demonstration of the exercise above.
    
• What's Next?

  What's Next?

  • URLDocumentation: FHIR Profiles and Adaptations

    Read about how to work with HL7 FHIR packages.
    

  • URLWorking with FHIR Profiles in InterSystems IRIS for Health

    Watch a presentation on how to work with HL7 FHIR Profiles in InterSystems IRIS for Health.

  • URLWorking with the FHIR Resource Repository

    Try a hands-on exercise on the InterSystems IRIS for Health HL7 FHIR Resource Repository.

  • URLFHIR R4 Integration QuickStart

    See how HL7 FHIR is supported in InterSystems IRIS for Health.

  • URLResource Guide: Learn FHIR for Software Developers

    Explore other learning resources about HL7 FHIR.
    

  • URLFHIR NPM Package Spec

    Read more on the HL7 FHIR Package Spec.
    

  • Share Your Feedback!

  • HL7® and FHIR® are the registered trademarks of Health Level Seven International and the use of these trademarks does not constitute an endorsement by HL7.