FHIR Implementation Guides & A Provider Directory Implementation

Introduction

Reaching the summit of Mount Everest is an extremely difficult and dangerous adventure. The first two people to accomplish this historical feat were Edmund Hillary and Tenzing Norgay. Tenzing Norgay was a Sherpa who helped Hillary plan, climb, and ultimately accomplish the goal of summitting Mount Everest.

Tenzing Norgay was an accomplished mountaineer and had been involved in numerous Everest scouting expeditions and several unsuccessful summit attempts prior to the successful summit with Hillary in 1953.

Without Tenzing Norgay, it is unlikely that Edmund Hillary would have known about:

• A climb path up the face of Everest that would yield the highest probability of success
• The intricacies of the Everest weather patterns and knowledge when it is safe to climb, and when to camp
• Equipment to bring, equipment to leave behind, and
• Climbing techniques and strategy specific to Everest.

Naturally, journalists wanted to know “Which of the two men had the right to the glory of being the first one, and who was merely the second, the follower?” Colonel Hunt, the expedition leader, declared, “They reached it together, as a team.”

Without Tenzing Norgay’s experience, knowledge, skill, and strength, Edmund Hillary’s place in history may have been limited to placement on a list of yet another mountaineer who unsuccessfully summitted Everest and largely forgotten by history.

When faced with a challenge, it’s often best to have a team of people who have attempted the challenge before, perhaps many times, and know which mistakes to avoid. Prior knowledge and experience is an invaluable tool helping to guide us on a path to success.

Thankfully, developing healthcare software isn’t nearly as perilous as climbing Mount Everest! Our industry nonetheless often encounters the same or similar interoperability challenges again and again, and thankfully, we have a way to document and share implementation decisions so that we can learn rapidly from one another in the FHIR Community.

Implementation Guides — Defined

The HL7 FHIR Specification defines an Implementation Guide as:

“A set of rules of how a particular interoperability or standards problem is solved — typically through the use of FHIR resources. This resource is used to gather all the parts of an implementation guide into a logical whole and to publish a computable definition of all the parts.”

An Implementation Guide is a set of rules about how FHIR may be used to solve a particular problem in healthcare. The FHIR Specification is quite broad and complete with many FHIR Resources, Search Parameters, Extensions, Profiles, and other capabilities. An Implementation Guide documents design decisions provides context for a developer, and affirmatively lists ingredients of FHIR concepts for the problem at hand.

It is worthwhile to clarify two terms. The FHIR Specification defines a FHIR Resource named “ImplementationGuide.” FHIR Servers can read, write, and search upon ImplementationGuide FHIR Resources. It is important to distinguish ImplementationGuides from an “Implementation Guide.” Implementation Guides are published on the web and can be generated using the FHIR Implementation Guide Publisher tool.

Provider Directory — An Example

Let’s look at a real-world example of an Implementation Guide by examining the PDEX Payer Network (or Plan-Net) Implementation Guide, and our implementation of it in the Helios FHIR Server — Provider Directory product.

What’s a Provider Directory?

A provider directory enables 3rd parties to develop applications that consumers and providers can query the participants in a payer’s network. This fulfills one of the core requirements of the CMS Final Rule and the 21st Century Cures Act. The CMS Final Rule focuses heavily on interoperability. It aims to start the process of liberating data and ensuring patients are the primary beneficiary of this process, and a provider directory is exactly what you need to accomplish this interoperability.

On January 2021, the CMS Interoperability and Patient Access Final Rule began to take effect (with a 6-month discretionary period due to the pandemic). By July 2021, CMS requires a new standard for both a patient access API and provider access API.

The patient access API impacts payer organizations in a significant way. It requires them to implement, test, and monitor a secure standard-based API that is accessible to third-party apps and developers. Importantly, these must be FHIR based APIs, and implementing the PDEX Payer Network (or Plan-Net) Implementation Guide satisfies this requirement.

A Quick Tour Through the Implementation Guide

The PDEX Payer Network Implementation Guide is described as:

“This implementation guide defines a FHIR interface to a health insurer’s insurance plans, their associated networks, and the organizations and providers that participate in these networks. Publication of this data through a standard FHIR-based API will enable third parties to develop applications through which consumers and providers can query the participants in a payer’s network that may provide services that address their health care needs.”

Put simply, this Implementation Guide defines an open FHIR-based API for querying health plan provider information.

For this article, we are going to focus only on two areas of the Implementation Guide and how they are supported in Helios FHIR Server:

• Resources
• Search Parameters

First, let’s have a look at the FHIR Resources involved in this Implementation Guide. We can see from the diagram that Practitioner and PractitionerRole are central to this Implementation Guide. Additionally, other FHIR Resources such as InsurancePlan, Network, Location, and Organization have key relationships in this implementation as well.

To learn how relationships between FHIR Resources are structured, see the References Between Resources section of The R in FHIR — Resources.

http://hl7.org/fhir/us/davinci-pdex-plan-net/index.html#overview-of-payer-directory-resource-relationships

Next, let’s have a look at the Search Parameters that are defined by this Implementation Guide.

http://hl7.org/fhir/us/davinci-pdex-plan-net/CapabilityStatement-plan-net.html#resource--details

There are quite a few search parameters defined in this Implementation Guide offering several convenient search paths for our resources, but not all Search Parameters are created equal. Some Search Parameters are defined in the base FHIR Specification, and some are specific to the Implementation Guide.

For example, Plannnet_sp_insuranceplan_name enables a client to search on the name or alias attribute of the InsurancePlan resource. This Search Parameter is the same as the name InsurancePlan Search Parameter defined by the base FHIR Specification.

Implementation Guides may introduce new Search Parameters, not defined in the base FHIR Specification. An example of an Implementation Guide — defined Search Parameter is Plannet_sp_insuranceplan_coverage_area. This Search Parameter enables searches on the InsurancePlan.coverageArea FHIR Path expression.

Configuring a FHIR Server for the PDEX Payer Network (or Plan-Net) Implementation Guide

The FHIR Specification is a large specification that encompasses many areas of the healthcare domain and use cases. In this Implementation Guide, we have seen that there are 8 FHIR Resources and a few dozen Search Parameters that a conformant FHIR Server solution needs to support.

Key Point: The Implementation Guide defines the minimum interface that SHALL/SHOULD/MAY be provided by a conformant server and will be expected by clients. If more than the minimum is implemented, clients are unlikely to be able to take advantage of those features, since they are developed for portability. If less than the minimum is provided, it may break some clients. A production implementation of this Implementation Guide should focus expressly on those FHIR Resources that are required for this Implementation Guide, and also implement the Search Parameters that are required too.

Wouldn’t it be great if a FHIR Server product did just that? That’s exactly what the Helios FHIR Server — Provider Directory product has done. Because of its modular architecture, only those database tables required to support the specified FHIR Resources in the Implementation Guide are created, only those Karaf bundles that support those Resources are started, and only those Search Parameters are activated. Should you ever need to add additional Resources and Search Parameters to your solution they are available in the distribution, however only those that are defined by the Implementation Guide are activated.

Downloading and Installing the Helios FHIR Server — Provider Directory

Next, let’s install the Helios FHIR Server, load some data, and test it using a test client! The steps below are similar to how we exercise our product and ensure it’s conformance during a FHIR Connectathon.

Navigate to https://heliossoftware.com/download-provider-directory-edition/ and download a copy of Helios FHIR Server. These instructions assume installation and testing on a local development environment/laptop for simplicity.

If not already installed, download and install Cassandra. Instructions for doing so can be found in our Installation Instructions in the Cassandra Quickstart guide.

Next, un-tar the Helios FHIR Server distribution:

$ tar xzvf ${helios-fhir-server-distribution.tar.gz}

And run Karaf:

$ cd ${helios-fhir-server-distribution}
$ bin/karaf

The Helios FHIR Server will automatically create the necessary keyspaces in Cassandra, and the necessary tables as well.

Running a bundle:list command in the Karaf console will show that only the FHIR Resources and Search Parameters required in the PDEX Payer Network Implementation Guide are, in fact Active.

One final step is to change the default security setting such that the Helios FHIR Server’s API can be read openly without authentication. This is an important step, as Provider Directory APIs are designed to be completely open for read-only access. Writes are, of course, restricted to authorized users.

The Helios FHIR Server ships with Basic Authentication turned on, so let’s use the administrative console to turn it off.

Open the following URL:

http://localhost:8181/ui/login

Login using the default credentials:

• Username: admin@heliossoftware.com
• Password: admin

Select the Settings menu item, flip Basic Enabled to off, and select the Update Settings button.

Let’s Generate Some Data!

Next, we’ll need some data. Thankfully, pdex-plan-net-sample-data open-source sample data tool developed by The MITRE Corporation is available expressly for this purpose. All of the MITRE resources mentioned in this article are available under a permissive Apache 2.0 license.

We have two options for data:

Option 1: Run the Ruby application yourself:

HL7-DaVinci/pdex-plan-net-sample-data

$ git clone git@github.com:HL7-DaVinci/pdex-plan-net-sample-data.git
$ cd pdex-plan-net-sample-data
$ bundle install
$ bundle exec ruby generate.rb

Next, cd into the output directory where the FHIR sample data has been generated and have a look!

$ cd output
$ ls
Endpoint HealthcareService InsurancePlan Location Organization OrganizationAffiliation Practitioner PractitionerRole

Option 2: Download our copy of the sample data if you’re unfamiliar with Ruby or do not wish to install it on your system:

Download and un-tar the sample data:

$ wget http://docs.heliossoftware.com/examples/output.tar.gz
$ tar -xvf output.tar.gz
$ cd output
$ ls
Endpoint    Location    Practitioner
HealthcareService   Organization    PractitionerRole
InsurancePlan    OrganizationAffiliation   fhir-importer-0.0.1-SNAPSHOT.jar

In addition to the data, we have also added the fhir-importer jar for convenience.

Import the Sample Data

If you are running Helios FHIR Server Locally, and you obtained a copy of the sample data using Option 2 above, you may simply issue this command to import the data.

java -jar fhir-importer-0.0.1-SNAPSHOT.jar -directory . -regex “.*.json”

If using Option 1, from above, and you wish to build and run the fhir-importer:

$ git clone git@github.com:HeliosSoftware/fhir-importer.git
$ cd fhir-importer
$ mvn clean install

The fhir-importer jar will reside in the /target folder.

Exercise the API

Now if we only had a sample client to use the API! Thanks again to the team at MITRE, we do. The plan-net_client open source reference implementation will issue FHIR-compliant REST calls to a provided open FHIR endpoint.

The plan-net_client is a sample client, and not at all intended to be for production use, or designed to be used as an example of a consumer-friendly application — it’s main purpose is to show how to a FHIR client may use the services of a Provider Directory FHIR Implementation Guide — compliant API.

There are two options for using the plan-net_client tool. The first is to download it from GitHub and run it locally:

HL7-DaVinci/plan-net_client

Alternatively, MITRE is hosting the code at this Heroku URL:

Plan Networks

Simply enter your URL into the text box on the home page, and you’re good to go! Here we are accessing the open Helios FHIR Server sandbox:

In the example below, after selecting the Pharmacies link on top, and selecting one of the Massachusetts insurance plans, we can not only see some of the sample data, but also see the exact FHIR query that was issued against the server:

Summary

In this article, we have:

• Provided a simple overview of a FHIR Implementation Guide, why they exist, and what they entail.
• Walked through, at a high-level, a real-world example of an Implementation Guide — the PDEX Payer Network (or Plan-Net) Implementation Guide, a requirement for the CMS Provider Directory regulation.
• Demonstrated how the Helios FHIR Server can easily implement an Implementation Guide, and provide support for precisely the FHIR components required of the Implementation Guide.