HAPI FHIR Server Validation - kind-lab/mimic-fhir GitHub Wiki

HAPI FHIR Server Validation

The HAPI FHIR server is used to process the FHIR resources and bundles. Follow steps 1 and 2 to get up and running validation.

Requires maven:

Apache Install Page
Mac OS X: brew install maven
Ubuntu: sudo apt-get install maven

1. Set up FHIR server locally:

Quickstart

cd ~/git/
git clone [email protected]:kind-lab/hapi-fhir-jpaserver-starter.git@mimic-package
cd hapi-fhir-jpaserver-starter
createdb hapi_r4
# (optional): edit src/main/resources/application.yaml to match your psql username/password
mvn jetty:run

Description of steps

Clone HAPI: Git clone the fork of the hapi-fhir-jpaserver-starter
- Switch to the mimic-package branch. This branch configures the connection to the mimic fhir package and the HAPI backend to postgres
HAPI backend: Create the Postgres database for HAPI fhir to use. Run CREATE DATABASE hapi_r4 from the psql terminal.
Launch HAPI: Now start the HAPI server by running mvn jetty:run from the terminal at the top level of the hapi-fhir-jpaserver-starter repo
- The startup will take 5-10 minutes the first time
Load terminology: Post terminology onto the server. The HAPI fhir server does not fully load the terminology from the mimic package, so we need to post them. Using the post_terminology script, post all the MIMIC CodeSystems and Valuesets
- Before running the script, clone mimic-profiles. This is the source of all the MIMIC terminology (NOTE we should debate putting the all the terminology into the mimic-fhir package, but it's nice to have just one source)
- The post_terminology script relies on you having the mimic-profiles repo locally. You will need to update the path to mimic-profiles in post_terminology.
- The HAPI server does not automatically expand the posted terminology. There is a background operation that will run and expand them. Typically after 5 minutes after posting this will start.

2. Validation Tests against HAPI FHIR server

There is a test folder for all the validation tests we have created for mimic-fhir. To run the tests there are two steps

Create conda environment with the environment.yaml
Run pytest in the tests folder. Ensure that the HAPI fhir server is running when you launch this!

Additional configurations for HAPI server

Updating the implementation guide (IG)

Update IG from a package on packages.fhir.org

Add reference implementation guides:

Update the src/main/resources/application.yaml, add desired implementation guide:
Example yaml update for implementation guide:

hapi:
  fhir:
    implementationguides:
      us-core:
        name: hl7.fhir.us.core
        version: 4.0.0

Update IG from a package stored on Github

Simplifier only allows one package with their free account, so as we expand FHIR work it would become a limitation. (Payed account is around ~$3000 a year) The alternative is to generate the package using SUSHI and then storing the package in Github

Generate package.tgz with SUSHI

Follow the guide from FSH School
In short run the two scripts _updatePublisher.sh and _genonce.sh inside your SUSHI project
package.tgz is generated to the output folder

Upload package.tgz to your Github repository
Update the src/main/resources/application.yaml, add reference to Github implementation guide:

copy the url from your Github repo for the package download

hapi:
  fhir:
    implementationguides:
      test-package:
        url: https://github.com/kind-lab/test-package/raw/main/test-pacakge-0.1.0.tgz
        name: test-package
        version: 0.1.0

Validation process

The two most common issues in the validation process are SQL script issues and FHIR package connection issues.

SQL script issue found

The steps to validate and fix a SQL script issue are:

Validate resource json against PNC package
If issue found, update the resource script with fixes
Recreate resource table (run sql script)
Regenerate resource json (run create_fhir_json.sql)
Drop new json into validation folder
Repeat steps 1-5 until no issues

FHIR package issue found

The steps to validate and fix a FHIR package issue are:

Validate resource json against PNC package
If issue found, update package (ie add valueset)
Regenerate package using sushi (can follow fsh tutorial)
Upload new package to [fhir-packages] repo
Update application.yaml in HAPI FHIR to reference new package URL
Restart HAPI FHIR server
Repeat steps 1-6 until no issues

Switching HAPI FHIR database connection

Attaching a postgres DB

Default HAPI FHIR will use a H2 database stored in a local file in the project. To set up a postgres DB:

Create new DB in postgres called 'hapi_r4'
Update pom.xml dependency
- Default is h2, update the
  - GroupId -> org.postgresql
  - ArtifactId -> postgresql
Update the application.yaml by removing H2 references and including:

spring:
  datasource:
    url: 'jdbc:postgresql://localhost:5432/hapi_r4'
    username: postgres
    password: postgres
    driverClassName: org.postgresql.Driver

Run mvn jetty:run and it will initialize the postgres DB
- First run after setting up postgres DB will be longer ( ~15 min)
- Second run will be fairly quick (<5 min)

Useful tables in HAPI FHIR DB

HAPI FHIR DB stores packages, valuesets, codesystems and resources
Useful tables https://hapifhir.io/hapi-fhir/docs/server_jpa/schema.html
- Hfj_forced_id: If a resource is added with a user defined ID, it will be referenced here
  - Gives you the internal resource_pid to find it in other tables
- Hfj_resource: Where every resource is stored
  - All the resource content is hashed with SHA-256
  - Has date of last updated
- Hfj_res_ver: Contains text from the resources, encoded
  - Use res_id to find a specific resource
  - The resource is serialied using FHIR JSON encoding and then compressed into a byte stream using GZIP compression. (so not readable in postgres, must be decoded in Java pipe)
- Hfj_res_link: Links from a resource to other resources