HAPI FHIR Software for IHE Connectathons

These instructions direct you to build the HAPI FHIR software from original source code. There is a Dockerized version that would likely get you to the same place. Our original attempts with that version failed, but that might have been pilot error. We will document the steps that worked for us (NA 2020).

Create Postgres Databases

• Create empty HAPI-FHIR databases. The application assumes an empty Postgres database for each of the supported versions.
  • We discovered this through trial and error. There may be ways to only create the databases you need.
  • Later versions of the software might require different databases.
  • We use the postgres role with the password "postgres". You will see that in the section when you configure Tomcat. You can choose a different password and/or use better Postgres

   createdb -U postgres fhirtest_dstu2
   createdb -U postgres fhirtest_dstu3
   createdb -U postgres fhirtest_r4
   createdb -U postgres fhirtest_r5

Create Folders for Lucene Files

The software assumes folders have been created to hold Lucene data. The path to the folders is passed to the software when you configure Tomcat (next section). We created (and later referenced) these folders:

   /opt/NA-2020/hapi-fhir-tomcat/lucene/dstu2
   /opt/NA-2020/hapi-fhir-tomcat/lucene/dstu3
   /opt/NA-2020/hapi-fhir-tomcat/lucene/r4
   /opt/NA-2020/hapi-fhir-tomcat/lucene/r5

• The parent folder (/opt/NA-2020/hapi-fhir-tomcat) is arbitrary; you may pick a different folder.
• There is no requirement that the four folders (dstu2, dstu3, r4, r5) have a common parent. The configuration below points to each folder separately.

Install and Configure Tomcat

We used Tomcat Version 8.5.50 for NA 2020. After you install the Tomcat software, you need to add some configuration. We added these lines in bin/catalina.sh:

   CATALINA_OPTS="-Dfhir.db.username=postgres $CATALINA_OPTS"
   CATALINA_OPTS="-Dfhir.db.password=postgres $CATALINA_OPTS"
   CATALINA_OPTS="-Dfhir.tdlpass=a,b $CATALINA_OPTS"
   CATALINA_OPTS="-Dfhir.baseurl=http://fhir-read-write:8080/fhir/baseR4 $CATALINA_OPTS"
   CATALINA_OPTS="-Dfhir.lucene.location.dstu2=/opt/NA-2020/hapi-fhir-tomcat/lucene/dstu2 -Dfhir.lucene.location.dstu3=/opt/NA-2020/hapi-fhir-tomcat/lucene/dstu3 -Dfhir.lucene.location.r4=/opt/NA-2020/hapi-fhir-tomcat/lucene/r4 -Dfhir.lucene.location.r5=/opt/NA-2020/hapi-fhir-tomcat/lucene/r5 $CATALINA_OPTS"

• Lines 1 and 2 set the username and password used to access the Postgres database. Make sure you are in alignment with how you configured Postgres.
• Line 3 was added because the software was throwing an exception without it (I believe). There did not seem to be any effect on the software itself if this value was used.
• Line 4 is needed for the application to know where the base URL is located.
  • fhir-read-write is the hostname that is known to this server and to users
  • /fhir needs to match the name of the war (fhir.war)
  • /baseR4 is for the R4 software. We only used R4 resources at NA 2020. Not sure what would change if you also needed DSTU3 resources.
• Line 5 gives the location of directories that are used to hold lucene files created by the application.
  • Synchronize with the folders created above.

Build the WAR File

• Clone a copy of the HAPI-FHIR server

   git clone https://github.com/jamesagnew/hapi-fhir.git

• Checkout the appropriate branch or version. For NA 2020, we used v4.1.0. Your event may use a more recent version.

   cd hapi-fhir
   git checkout v4.1.0

• Modify source code

There are small changes necessary to configure the software. These are completed directly in the source code and not in a configuration file. Please see the section at the bottom of this page for details.

• Build the war file

Use the mvn command to build the war file. You want to use the flag -DskipTests unless you want to wait a long time for the unit tests to complete.

   mvn -DskipTests install

• Copy the war file to the tomcat server

   cp hapi-fhir-jpaserver-uhnfhirtest/target/hapi-fhir-jpaserver.war $TOMCAT/webapps/fhir.war

Execute in Tomcat

• Start the Tomcat server

   cd $TOMCAT
   chmod +x bin/*sh
   ./bin/startup.sh

Source Code Modification Details

You will need to modify three files:

hapi-fhir-jpaserver-base/src/main/java/ca/uhn/fhir/jpa/term/BaseTermReadSvcImpl.java
hapi-fhir-jpaserver-uhnfhirtest/src/main/java/ca/uhn/fhirtest/config/FhirTesterConfig.java
hapi-fhir-jpaserver-uhnfhirtest/src/main/java/ca/uhn/fhirtest/config/TestR4Config.java

BaseTermReadSvcImpl.java

We found that the application was throwing a null pointer exception. We modified the method isNotSafeToPreExpandValueSets as follows:

        private boolean isNotSafeToPreExpandValueSets() {
-               return !myDeferredStorageSvc.isStorageQueueEmpty();
+               if (myDeferredStorageSvc != null) {
+                       return !myDeferredStorageSvc.isStorageQueueEmpty();
+               } else {
+                       return false;
+               }
        }

FhirTesterConfig.java This file controls the menu that lists all target systems. It allows you to configure participant FHIR servers so that the Web UI can be used to directly query an individual server.

• Find the method public TesterConfig testerConfig().
• Remove or comment out addServer() entries that point to public servers that not of interest (e.g., the Vonk - Firely server)
• Add entries for each participant FHIR server. You can follow the existing pattern in the source code.

TestR4Config.java

This file sets aliases for the R4 server. The source code assumes different public URLs, with both http and https. We modified for a single URL (http only) as follows:

git diff hapi-fhir-jpaserver-uhnfhirtest/src/main/java/ca/uhn/fhirtest/config/TestR4Config.java
diff --git a/hapi-fhir-jpaserver-uhnfhirtest/src/main/java/ca/uhn/fhirtest/config/TestR4Config.java b/hapi-fhir-jpaserver-uhnfhirtest/src/main/java/ca/uhn/fhirtest/config/TestR4Config.java
index 6b836aab1b..7d26c1ee8b 100644
--- a/hapi-fhir-jpaserver-uhnfhirtest/src/main/java/ca/uhn/fhirtest/config/TestR4Config.java
+++ b/hapi-fhir-jpaserver-uhnfhirtest/src/main/java/ca/uhn/fhirtest/config/TestR4Config.java
@@ -56,10 +56,7 @@ public class TestR4Config extends BaseJavaConfigR4 {
                retVal.setAllowMultipleDelete(true);
                retVal.setAllowInlineMatchUrlReferences(true);
                retVal.setAllowExternalReferences(true);
-               retVal.getTreatBaseUrlsAsLocal().add("http://hapi.fhir.org/baseR4");
-               retVal.getTreatBaseUrlsAsLocal().add("https://hapi.fhir.org/baseR4");
-               retVal.getTreatBaseUrlsAsLocal().add("http://fhirtest.uhn.ca/baseR4");
-               retVal.getTreatBaseUrlsAsLocal().add("https://fhirtest.uhn.ca/baseR4");
+               retVal.getTreatBaseUrlsAsLocal().add("http://fhir-read-write:8080/fhir/baseR4");
                retVal.setIndexMissingFields(DaoConfig.IndexEnabledEnum.ENABLED);
                retVal.setCountSearchResultsUpTo(TestR4Config.COUNT_SEARCH_RESULTS_UP_TO);
                retVal.setFetchSizeDefaultMaximum(10000);