PCT Payer Server

This server is based on the HAPI FHIR JPA Starter server with modifications to support Patient Cost Transparency. This version of the reference Implementation supports the STU1 version of the Da Vinci Patient Cost Transparency Implementation Guide

The primary file for processing the Good Faith Estimate is GFESubmitProvider.java

Foundry

A live demo is hosted by HL7 FHIR Foundry.

Prerequisites

In order to use this sample, you should have:

• This project checked out. You may wish to create a GitHub Fork of the project and check that out instead so that you can customize the project and save the results to GitHub.

and either

• Oracle Java (JDK) installed: Minimum JDK8 or newer.
• Apache Maven build tool (newest version)

Configuration via overridden application.yaml file and using Docker

You can customize HAPI by telling HAPI to look for the configuration file in a different location, eg.:

docker run -p 8090:8083 -v $(pwd)/yourLocalFolder:/configs -e "--spring.config.location=file:///configs/another.application.yaml" hapiproject/hapi:latest

Here, the configuration file (another.application.yaml) is placed locally in the folder yourLocalFolder.

docker run -p 8090:8083 -e "--spring.config.location=classpath:/another.application.yaml" hapiproject/hapi:latest

Here, the configuration file (another.application.yaml) is part of the compiled set of resources.

Example using docker-compose.yml for docker-compose

version: '3.7'
services:
  web:
    image: "hapiproject/hapi:latest"
    ports:
      - "8090:8083"
    configs:
      - source: hapi
        target: /data/hapi/application.yaml
    volumes:
      - hapi-data:/data/hapi
    environment:
      SPRING_CONFIG_LOCATION: 'file:///data/hapi/application.yaml'
configs:
  hapi:
     external: true
volumes:
    hapi-data:
        external: true

Running locally

The easiest way to run this server entirely depends on your environment requirements. At least, the following 4 ways are supported:

Note that running it on windows may require the use of WSL as there is a name file length issue. Running in VS Code in debug seems to work without issue.

Using jetty

mvn jetty:run

If you need to run this server on a different port (using Maven), you can change the port in the run command as follows:

mvn -Djetty.port=8888 jetty:run

Server will then be accessible at http://localhost:8888/ and eg. http://localhost:8888/fhir/metadata. Remember to adjust you overlay configuration in the application.yaml to eg.

    tester:
      -
          id: home
          name: Local Tester
          server_address: 'http://localhost:8888/fhir'
          refuse_to_fetch_third_party_urls: false
          fhir_version: R4

Using Spring Boot with :run

mvn clean spring-boot:run -Pboot

Server will then be accessible at http://localhost:8083/ and eg. http://localhost:8083/fhir/metadata. Remember to adjust you overlay configuration in the application.yaml to eg.

    tester:
      -
          id: home
          name: Local Tester
          server_address: 'http://localhost:8083/fhir'
          refuse_to_fetch_third_party_urls: false
          fhir_version: R4

Using Spring Boot

mvn clean package spring-boot:repackage -Pboot && java -jar target/ROOT.war

Server will then be accessible at http://localhost:8083/ and eg. http://localhost:8083/fhir/metadata. Remember to adjust you overlay configuration in the application.yaml to eg.

    tester:
      -
          id: home
          name: Local Tester
          server_address: 'http://localhost:8083/fhir'
          refuse_to_fetch_third_party_urls: false
          fhir_version: R4

Using Spring Boot and Google distroless

mvn clean package com.google.cloud.tools:jib-maven-plugin:dockerBuild -Dimage=distroless-hapi && docker run -p 8083:8083 distroless-hapi

Server will then be accessible at http://localhost:8083/ and eg. http://localhost:8083/fhir/metadata. Remember to adjust you overlay configuration in the application.yaml to eg.

    tester:
      -
          id: home
          name: Local Tester
          server_address: 'http://localhost:8083/fhir'
          refuse_to_fetch_third_party_urls: false
          fhir_version: R4

Using the Dockerfile and multistage build

./build-docker-image.sh && docker run -p 8083:8083 hapi-fhir/hapi-fhir-jpaserver-starter:latest

Server will then be accessible at http://localhost:8083/ and eg. http://localhost:8083/fhir/metadata. Remember to adjust you overlay configuration in the application.yaml to eg.

    tester:
      -
          id: home
          name: Local Tester
          server_address: 'http://localhost:8083/fhir'
          refuse_to_fetch_third_party_urls: false
          fhir_version: R4

Configurations

Much of this HAPI starter project can be configured using the yaml file in src/main/resources/application.yaml. By default, this starter project is configured to use H2 as the database.

MySql configuration

To configure the starter app to use MySQL, instead of the default H2, update the application.yaml file to have the following:

spring:
  datasource:
    url: 'jdbc:mysql://localhost:3306/hapi_dstu3'
    username: admin
    password: admin
    driverClassName: com.mysql.jdbc.Driver

On some systems, it might be necessary to override hibernate's default naming strategy. The naming strategy must be set using spring.jpa.hibernate.physical_naming_strategy.

spring:
  jpa:
    hibernate.physical_naming_strategy: NAME_OF_PREFERRED_STRATEGY

On linux systems or when using docker mysql containers, it will be necessary to review the case-sensitive setup for mysql schema identifiers. See https://dev.mysql.com/doc/refman/8.0/en/identifier-case-sensitivity.html. We suggest you set lower_case_table_names=1 during mysql startup.

PostgreSQL configuration

To configure the starter app to use PostgreSQL, instead of the default H2, update the application.yaml file to have the following:

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

Because the integration tests within the project rely on the default H2 database configuration, it is important to either explicity skip the integration tests during the build process, i.e., mvn install -DskipTests, or delete the tests altogether. Failure to skip or delete the tests once you've configured PostgreSQL for the datasource.driver, datasource.url, and hibernate.dialect as outlined above will result in build errors and compilation failure.

Customizing The Web Testpage UI

The UI that comes with this server is an exact clone of the server available at http://hapi.fhir.org. You may skin this UI if you'd like. For example, you might change the introductory text or replace the logo with your own.

The UI is customized using Thymeleaf template files. You might want to learn more about Thymeleaf, but you don't necessarily need to: they are quite easy to figure out.

Several template files that can be customized are found in the following directory: https://github.com/hapifhir/hapi-fhir-jpaserver-starter/tree/master/src/main/webapp/WEB-INF/templates

Deploying to an Application Server

Using the Maven-Embedded Jetty method above is convenient, but it is not a good solution if you want to leave the server running in the background.

Most people who are using HAPI FHIR JPA as a server that is accessible to other people (whether internally on your network or publically hosted) will do so using an Application Server, such as Apache Tomcat or Jetty. Note that any Servlet 3.0+ compatible Web Container will work (e.g Wildfly, Websphere, etc.).

Tomcat is very popular, so it is a good choice simply because you will be able to find many tutorials online. Jetty is a great alternative due to its fast startup time and good overall performance.

To deploy to a container, you should first build the project:

mvn clean install

This will create a file called ROOT.war in your target directory. This should be installed in your Web Container according to the instructions for your particular container. For example, if you are using Tomcat, you will want to copy this file to the webapps/ directory.

Again, browse to the following link to use the server (note that the port 8083 may not be correct depending on how your server is configured).

http://localhost:8083/

You will then be able access the JPA server e.g. using http://localhost:8083/fhir/metadata.

If you would like it to be hosted at eg. hapi-fhir-jpaserver, eg. http://localhost:8083/hapi-fhir-jpaserver/ or http://localhost:8083/hapi-fhir-jpaserver/fhir/metadata - then rename the WAR file to hapi-fhir-jpaserver.war and adjust the overlay configuration accordingly e.g.

    tester:
      -
          id: home
          name: Local Tester
          server_address: 'http://localhost:8083/hapi-fhir-jpaserver/fhir'
          refuse_to_fetch_third_party_urls: false
          fhir_version: R4

Deploy with docker compose

Docker compose is a simple option to build and deploy container. To deploy with docker compose, you should build the project with mvn clean install and then bring up the containers with docker-compose up -d --build. The server can be reached at http://localhost:8083/.

In order to use another port, change the ports parameter inside docker-compose.yml to 8888:8083, where 8888 is a port of your choice.

The docker compose set also includes my MySQL database, if you choose to use MySQL instead of H2, change the following properties in application.yaml:

spring:
  datasource:
    url: 'jdbc:mysql://hapi-fhir-mysql:3306/hapi'
    username: admin
    password: admin
    driverClassName: com.mysql.jdbc.Driver

Running hapi-fhir-jpaserver directly from IntelliJ as Spring Boot

Make sure you run with the maven profile called boot and NOT also jetty. Then you are ready to press debug the project directly without any extra Application Servers.

Running hapi-fhir-jpaserver-example in Tomcat from IntelliJ

Install Tomcat.

Make sure you have Tomcat set up in IntelliJ.

• File->Settings->Build, Execution, Deployment->Application Servers
• Click +
• Select "Tomcat Server"
• Enter the path to your tomcat deployment for both Tomcat Home (IntelliJ will fill in base directory for you)

Add a Run Configuration for running hapi-fhir-jpaserver-example under Tomcat

• Run->Edit Configurations
• Click the green +
• Select Tomcat Server, Local
• Change the name to whatever you wish
• Uncheck the "After launch" checkbox
• On the "Deployment" tab, click the green +
• Select "Artifact"
• Select "hapi-fhir-jpaserver-example:war"
• In "Application context" type /hapi

Run the configuration.

• You should now have an "Application Servers" in the list of windows at the bottom.
• Click it.
• Select your server, and click the green triangle (or the bug if you want to debug)
• Wait for the console output to stop

It is important to use MySQL5Dialect when using MySQL version 5+.

Enabling Subscriptions

The server may be configured with subscription support by enabling properties in the application.yaml file:

• hapi.fhir.subscription.resthook_enabled - Enables REST Hook subscriptions, where the server will make an outgoing connection to a remote REST server

• hapi.fhir.subscription.email.* - Enables email subscriptions. Note that you must also provide the connection details for a usable SMTP server.

• hapi.fhir.subscription.websocket_enabled - Enables websocket subscriptions. With this enabled, your server will accept incoming websocket connections on the following URL (this example uses the default context path and port, you may need to tweak depending on your deployment environment): ws://localhost:8083/websocket

Enabling CQL

Set hapi.fhir.cql_enabled=true in the application.yaml file to enable Clinical Quality Language on this server.

Enabling MDM (EMPI)

Set hapi.fhir.mdm_enabled=true in the application.yaml file to enable MDM on this server. The MDM matching rules are configured in mdm-rules.json. The rules in this example file should be replaced with actual matching rules appropriate to your data. Note that MDM relies on subscriptions, so for MDM to work, subscriptions must be enabled.

Using Elasticsearch

By default, the server will use embedded lucene indexes for terminology and fulltext indexing purposes. You can switch this to using lucene by editing the properties in application.yaml

For example:

elasticsearch.enabled=true
elasticsearch.rest_url=localhost:9200
elasticsearch.username=SomeUsername
elasticsearch.password=SomePassword
elasticsearch.protocol=http
elasticsearch.required_index_status=YELLOW
elasticsearch.schema_management_strategy=CREATE

Enabling LastN

Set hapi.fhir.lastn_enabled=true in the application.yaml file to enable the $lastn operation on this server. Note that the $lastn operation relies on Elasticsearch, so for $lastn to work, indexing must be enabled using Elasticsearch.

Changing cached search results time

It is possible to change the cached search results time. The option reuse_cached_search_results_millis in the [application.yaml] is 6000 miliseconds by default. Set reuse_cached_search_results_millis: -1 in the [application.yaml] file to ignore the cache time every search.

Build the distroless variant of the image (for lower footprint and improved security)

The default Dockerfile contains a release-distroless stage to build a variant of the image using the gcr.io/distroless/java-debian10:11 base image:

docker build --target=release-distroless -t hapi-fhir:distroless .

Note that distroless images are also automatically build and pushed to the container registry, see the -distroless suffix in the image tags.

Adding custom operations

To add a custom operation, refer to the documentation in the core hapi-fhir libraries here.

Within hapi-fhir-jpaserver-starter, create a generic class (that does not extend or implement any classes or interfaces), add the @Operation as a method within the generic class, and then register the class as a provider using RestfulServer.registerProvider().

Questions and Contributions

Questions about the project can be asked in the Da Vinci PCT stream on the FHIR Zulip Chat.

This project welcomes Pull Requests. Any issues identified with the RI should be submitted via the GitHub issue tracker.

As of October 1, 2022, The Lantana Consulting Group is responsible for the management and maintenance of this Reference Implementation. In addition to posting on FHIR Zulip Chat channel mentioned above you can contact Corey Spears for questions or requests.