HAPI FHIR Server Validation

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 git@github.com: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

1. 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

2. Upload package.tgz to your Github repository
3. 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:

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

FHIR package issue found

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

1. Validate resource json against PNC package
2. If issue found, update package (ie add valueset)
3. Regenerate package using sushi (can follow fsh tutorial)
4. Upload new package to [fhir-packages] repo
5. Update application.yaml in HAPI FHIR to reference new package URL
6. Restart HAPI FHIR server
7. 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