Skip to content

Home

Jump to bottom
Vanessa Fotso edited this page Sep 7, 2022 · 7 revisions

Welcome to the Drug Formulary Server Reference Implementation wiki!

Introduction

This service is a reference FHIR server for the Da Vinci US Drug Formulary Implementation Guide. It is based on the HAPI FHIR JPA Server. This service provides a FHIR RESTful API for reading a health insurer's drug formulary information for patients/consumers. It can be accessed through an unauthenticated API to query the list of health plans provided by a payer and the medication and costs for each plan; or through an authenticated API that allows members/patients to query their individual formularies (if currently enrolled in a plan) and see which medications are covered by their insurance plan. The APIs returns data format corresponding to FHIR version R4.

Security

The authenticated access API follows the SMART App Launch protocol of the SMART on FHIR API standards. The SMART App Launch protocol is intended for use by user-facing apps, where access is granted based on the end user entering their existing login credentials (username and password).

Features

Read Only

This server only allows other systems to read data from the available endpoints (unless having admin privilege).

You may care to view the Drug Formulary STU2 Postman Collection.

Public Endpoints

  • Metadata (/metadata): query to this endpoint returns the capability statement describing the services.
  • InsurancePlan (/InsurancePlan): enables users to query payer insurance plan or drug insurance offering comprised of drug benefits including a definition of drug tiers and their associated cost-sharing models and additional information about the plan.
  • Basic (/Basic): enables query for a drug's relationship to a drug plan, including drug tier, prior authorization requirements, and more.
  • MedicationKnowledge (/MedicationKnowledge): enables query for details about each medication within a formulary.
  • Location (/Location): enables query for a geographic region where an insurance plan coverage is available.

Protected Endpoints

In compliance with the Centers for Medicare and Medicaid Services (“CMS”) Interoperability and Patient Access Final Rule (CMS-9115-F), this server allows users to access their formulary information using registered, third-party client applications. The secured endpoints are:

  • Patient (/Patient): enable members to securely read their Personal details.
  • Coverage (/Coverage): enables members to securely retrieve their insurance plans details.

SMART on FHIR Authorization server

The ca.uhn.fhir.jpa.starter.authorization package contains a very basic OAuth server. It provides functionality for token introspection, client registration, user registration, and OAuth 2.0 authorization_code grant flow (token and authorize endpoints). Check the Getting Started page page for details on the authorization workflow or learn more from the SMART on FHIR IG.

This authorization server uses a SQL database to store users and clients. This is exposed in the debug endpoint. A homegrown auth server was built here instead of using a 3rd party identity provider because the SMART on FHIR flow includes non-standard patient context details. This would require proxying requests to the identity server. For production systems it is not recommended to use this authorization server.

The configuration for these endpoints is found in src/main/webapp/WEB-INF/web.xml.

SMART on FHIR PatientAuthorizationInterceptor

The PatientAuthorizationInterceptor checks the access token on every request to determine what resources the request will have access to. There are 3 rules here:

  1. If the token is the admin token, then the user has access to everything (all CRUD operations on all resources).

  2. If the token is valid then the user has access to specific resources within their compartment (Patient, Coverage) and non-personalized (public) resources (i.e. InsurancePlan or MedicationKnowledge).

  3. Otherwise, the only the public endpoints are available.

SMART on FHIR .well-known/smart-configuration file

To support the SMART on FHIR spec a .well-known/smart-configuration file is hosted. The configuration for this endpoint is found in src/main/webapp/WEB-INF/web.xml. The controller is found in the ca.uhn.fhir.jpa.starter.wellknown package.

Note: the MetadataProvider.java file also includes the authorization details.

Bulk Data Export

This server supports exporting Formularies data in bulk following the FHIR Bulk Data specification. Instead of making individual requests to gather data, the bulk data export supports exporting all available formularies data not related to a patient at once.

Service Method Description
/InsurancePlan/$export GET Request to export all InsurancePlan, Basic, MedicationKnowledge, and Location resource types containing formulary related data associated with all formulary related plans.
/InsurancePlan/[:id]/$export GET Request to export all InsurancePlan, Basic, MedicationKnowledge, and Location resource types containing formulary related data associated with the specific plan.

The export functionality is implemented in src/main/java/ca/uhn/fhir/jpa/starter/ExportInterceptor.java and the configuration can be found in src/main/java/ca/uhn/fhir/jpa/starter/ExportConfig.java.

Check the FHIR Server Interaction page for detailed bulk data request flow.

Debug endpoints

The ca.uhn.fhir.jpa.starter.debug package contains endpoints for debug use. They include:

  • /Clients to get a webpage view of the Clients table in the authorization server
  • /Users to get a webpage view of the Users table in the authorization server
  • /Log to get the raw text of the logs
  • /UpdateClient?client_id={id} to PUT a client.
{
    "id": "{id}",
    "secret": "{secret}",
    "redirectUri": "{redirect uri}"
}

This last request is helpful in Connectathons since every time the server is restarted the clients table is not persisted. As such instead of making clients re-register and obtain new credentials every time you can add the client back with the same details as before.

Clone this wiki locally