Bulk FHIR Step by StepContestant

FHIR repositories, applications and servers typically serve clinical data in small quantities, whether to return data about a patient, their medications, vaccines, allergies, among other information. However, it is common for a large amount of data in FHIR/JSON format to be requested to be used to load into Data Lakes, identifying study cohorts, population health, or transferring data from one EHR to another. To meet these business scenarios that require large extractions and loads of data, it is recommended to use the FHIR Bulk Data Access feature provided by HL7 institution.

The InterSystems IRIS for Health implements the FHIR Bulk Data Access with the feature BFC - Bulk FHIR Coordinator (https://docs.intersystems.com/irisforhealthlatest/csp/docbook/DocBook.UI...). According InterSystems documentation, BFC "simplify the FHIR bulk data interaction for clients and to not overwhelm a FHIR server with bulk data requests, the InterSystems Bulk FHIR Coordinator(BFC) mediates the interaction between a bulk data client and a FHIR resource server endpoint for bulk data requests. The Bulk FHIR Coordinator can facilitate bulk FHIR export for FHIR resource servers that do not natively support the bulk data interaction." The diagram into the documentation illustrates how the Bulk FHIR Coordinator mediates the interaction between a client and FHIR endpoints:

So if you want to migrate from any FHIR server to IRIS for Health, you can use BFC to connect on a target FHIR server to get all data you need as json files (ndjson resources), and import into your InterSystems FHIR server.

In this article you will learn step by step how to configure and use BFC to obtain all patient data from an FHIR repository into JSON files for later use.

Step 1 - Get/Configure an IRIS for Health Instance to use BFC

If you don't have an IRIS for Health in use, you can get one here: https://openexchange.intersystems.com/package/iris-fhir-template. Follow these installations procedures:

1.1 Docker setup:

Clone/git pull the repo into any local directory

git clone https://github.com/intersystems-community/iris-fhir-template.git

Open the terminal in this directory and run:

docker-compose up -d

1.2 Or IPM setup (required an IRIS for Health running):

Open IRIS for Health installation with IPM client installed. Call in any namespace:

USER>zpm "install fhir-server"

This will install FHIR server in FHIRSERVER namespace.

Or call the following for installing programmatically:

set sc=$zpm("install fhir-server")

Step 2 - Create a new security credential

1. Access the Management Portal for the namespace FHIRSERVER (http://localhost:32783/csp/sys/%25CSP.Portal.Home.zen?$NAMESPACE=FHIRSERVER).

2. Go to Interoperability > Configure > Credentials:

3. Set the BulkCreds values and save:

• ID: BulkCreds
• User Name: _SYSTEM
• Password: SYS

Step 3 - Configure the BFC - Bulk Data Coordinator

1. Go to BFC UI (http://localhost:32783/csp/healthshare/fhirserver/bulkfhir/index.html):

2. Click the button + New Configuration > Create New:

3. Set the configuration settings:

• Name: BFC_Patients
• BFC Endpoint (any relative path): /bulkfhir/patients
• Keep all other settings as they are

4. Click Next button.

5. Select HS.BulkFHIR.Auth.BasicAuth.Adapter and click the Next button

6. Select the HS.BulkFHIR.Fetch.PureFHIR.Adapter for Fetch Adapter field and set the following values:

• Endpoint URL: http://fhir-template:52773/fhir/r4
•  
• SSL Configuration: BFC_SSL
• Authorization Type: HTTP
• HTTP Credential ID: BulkCreds
• Accept the default values for all other fields

7. Click the button Next.

8. Select the value HS.BulkFHIR.Storage.File.Adapter for Storage Adapter field and set the following values:

• Storage Adapter: HS.BulkFHIR.Storage.File.Adapter
• File URL: /bulkfhir/file
• Directory: /usr/irissys/mgr/Temp/BulkFHIR/FHIRSERVER/

9. Click the button Next.

10. Review the configuration and click the button Configure in the bottom of the page:

11. You will see the success message: 

Step 4 (Final Step) - Get your bulk data

1. Go to Exports:

2. Click the button + New Export Request:

3. Select the Configuration field BFC_Patients value and click the button Next

4. Select the Patient option and click the button Export Now:

5. You get a sucess message:

6. Click the button Refresh on the Top of the page:

7. See the session of the configuration BFC_Patients completed:

8. Click the last button Download ():

9. See the the exported json files list:

10. Download any file and see its content:

11. To initiate a bulk FHIR export from a REST client, send a GET request to your BFC endpoint indicating the desired operation, for example:

•     System — GET https://bfcEndpoint/$export
•     Patient — GET https://bfcEndpoint/Patient/$export
•     Group — GET https://bfcEndpoint/Group/groupID/$export

12. More details how to use with API: https://docs.intersystems.com/healthconnectlatest/csp/docbook/DocBook.UI...

13. More details how to use BFC:

• https://docs.intersystems.com/healthconnectlatest/csp/docbook/DocBook.UI...
• https://www.youtube.com/watch?v=J-AVP9MFMWI

Enjoy!!