Topic outline

• Creating a Simple FHIR Facade

  Creating a Simple FHIR Facade

  Content Type
  Exercise

  Duration
  20m

  Level
  Intermediate

  Use an instance of InterSystems IRIS® for Health to create and configure a FHIR Facade architecture, allowing your system to accept HL7® FHIR® requests and return FHIR data even when data is not originally stored in this format. To create the FHIR Facade, you will use the FHIR Interoperability Adapter; this creates a new interoperability REST endpoint that uses special business hosts to process FHIR requests in a production. This production can then be used to facilitate the retrieval and transformation of data and return the requested data.

  In this exercise, you will create a FHIR Facade for a medical facility that stores EMR data in an internal format. This facility has a REST API configured that returns patient details in JSON format, but they have been receiving requests for patient data in the FHIR format.

  Note:

  This exercise uses the FHIR Object Model to transform data directly into the FHIR format from a custom data format. This method should only be used if you will not transform your data into any other formats. If you need to transform your data into other formats, you should use SDA as an intermediary format. Refer to Transforming Data into the HL7 FHIR Format (online course, 30m) for details.

  Learning Objectives

  • Use the Interoperability Adapter to create a REST endpoint for handling FHIR requests in a production.
  • Apply data transformation techniques to convert patient data into the FHIR format.
  • Configure and test a production that integrates a business process to process FHIR requests and return FHIR data.

  Prerequisites

  • If you are not yet familiar with the DTL editor, try Creating a Data Transformation (exercise, 20m).
  • Get an introduction to FHIR Facades (video, 4m).
• Start the Exercise

  Start the Exercise

  Use the online lab provided to complete this exercise.

  •  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.
  • Try the existing REST API
    

    Before creating a FHIR Facade that will allow the medical facility to return data in the FHIR format, test the existing REST API to verify that you can add patients and retrieve their information in the JSON format. 

    1. Open Postman using the icon on the desktop, and send a new request to the EMR REST API to create a new patient:
       1. HTTP: http://localhost:52773/api/EMR/patient
       2. Request type: POST
       3. Header name: Content-Type
       4. Header value: application/json
       5. Body:
          
          Begin code:

          {"Identifier":"22", 
          "FirstName":"Amy", 
          "LastName":"Smith", 
          "DOB":"2001-01-01", 
          "Gender":"female"} 
          

          End code.
          You should receive a 201 status, indicating that the request was sent successfully. Next, you can send a new request to retrieve the patient information.
    2. Send a new request to the EMR REST API:
       1. HTTP: http://localhost:52773/api/EMR/patient/22
       2. Request type: GET
          The request will return the patient details that you just added to the EMR, in JSON format.
  • Create and test a new Interoperability Adapter

    In cases where you need to process a FHIR request without leveraging the internal repository of a FHIR server, you can use the FHIR Interoperability Adapter to receive requests into an interoperability production.

    1. Open Terminal using the icon on the desktop, and start an InterSystems IRIS terminal by running the command iris terminal irishealth. Sign in with the username tech and password demo. 
    2. Switch to the FINAL namespace, if needed:
       
       Begin code:

       Set $namespace = "FINAL"
       

       End code.
    3. Run the following command to install a new interoperability adapter, with a specific URL for the interoperability REST endpoint:
       
       Begin code:

       do ##class(HS.FHIRServer.Installer).InteropAdapterConfig("/MyFHIREndpoint/r4facade")

       End code.
    4. Open the Management Portal using the icon on the desktop. Sign in with the credentials tech and demo, and make sure you are in the FINAL namespace. Then navigate to Interoperability > Configure > Production.
    5. Open the FINALPKG.FoundationProduction production, and click the plus symbol next to Operations to add a new business operation with the following settings:
       
       • Class: Demo.Int.BO.EMRRESTOperation
       • Enable Now: selected
    6. Configure the new business operation with the following settings. Make sure to click Apply to save these settings:
       
       • HTTP Server: localhost
       • Port: 52773
       • URL: /api/EMR/patient
    7. Click Production Settings, and select Testing Enabled under Development and Debugging. Click Apply to save this setting.
    8. Start the production.
    9. Select the new business operation, Demo.Int.BO.EMRRESTOperation, and click Test under the Actions tab.
    10. In the testing window, enter the following settings, then click Invoke Testing Service.
        
        • Request Type: Demo.Int.Msg.GetPatient
        • Identifier: 22

    In the test results section, you should see the details of patient 22 that you added to the EMR earlier.

  • Transform patient data into the FHIR format

    Now that you have configured an interoperability adapter that allows you to send requests to the EMR, you will create a data transformation that converts the JSON data returned by the EMR into the FHIR format.

    1. In the Management Portal, navigate to Interoperability > Build > Data Transformations.
    2. Create a new data transformation with the following settings:
       1. Package: Final
       2. Name: DTL.PatientToFHIR
       3. Source Class: Demo.Int.Msg.Patient
       4. Target Class: HS.FHIR.DTL.vR4.Model.Resource.Patient
    3. Use the data transformation editor to map the following fields from the source document to the target:
       

       Source	Target
       LastName	name().family
       FirstName	name().given()
       DOB	birthDate
       Gender	gender
       Identifier	identifier().value

    4. Add two set actions to set the following properties in the target document:
       
       • Property:target.identifier.(1).type.text
         
         • Value: "SSN"
       • Property: target.name.(1).use
         
         • Value: "official"
    5. Compile the data transformation.
       After compiling, add your new data transformation to the business process that will be used in your production.
    6. Navigate to Interoperability > Build > Business Processes.
    7. Open the Final.BP.GetPatient business process.
    8. Add the new data transformation to the business process.
       
       1. Select the Patient Info to Resource activity.
       2. Under the Activity tab, use the magnifying glass to select Final.DTL.PatientToFHIR as the Data Transformation Class.
    9. Compile the business process.
  • Add the business process to the production and test

    1. Return to the FINALPKG.FoundationProduction production.
    2. Click the plus symbol next to Processes to add a business process with the following settings:
       
       1. Class: Final.BP.GetPatient
       2. Name: Get Patient
       3. Enable Now: Selected
    3. Select the InteropService business service and change the Target Config Name to Get Patient. Click Apply to save this setting.
    4. Using Postman, send the following request using the patient ID of the patient you added to the EMR in Task 1. 
       
       1. HTTP: http://localhost:52773/MyFHIREndpoint/r4facade/Patient/22
       2. Request Type:GET
       3. Header Name: Accept
       4. Header Value: application/fhir+json

    The response to this request should show the patient details in FHIR JSON format.

    You have now created a FHIR Facade using the FHIR Interoperability Adapter. This setup allows your system to accept FHIR requests and return FHIR data even when your data is not stored in the FHIR format. Using the built-in features of InterSystems IRIS for Health—including data transformations and BPL business processes—you configured the FHIR Facade to take data stored in an internal format and make it available as FHIR resources to a requesting system. With the FHIR Facade, you can easily share data in the FHIR format without changing your storage or modifying interoperability configurations already in place.

• What's Next?

  What's Next?
  • Read more about the FHIR Interoperability Adapter (documentation, 6m).
  • Build an application that stores data in the FHIR format (learning path, 4h 15m).

  • Share Your Feedback!