In this post, I will describe popEYE, a REST API that we have built for Clinical Quality Metrics (CQM) Calculations. We have built popEYE by modifying popHealth v2.1 to work as a RESTful API service so that EHR vendors or Healthcare organizations can calculate CQMs in a multi-practice environment in a scalable manner over millions of patient records with simple API calls.

CQM Background

One of the critical challenges in calculating CQMs is modeling complex query logic and to keep it up-to-date based on changes mandated under Meaningful Use (MU) requirements. Making a system that meets these requirements can take a toll on an EHR company, whose primary objective is to really develop a simple, user-friendly EHR (a very interesting study on this recently). Another challenge in calculating CQMs is achieving scalability; performing such complex queries across all patient records and for multiple EHR users is a computationally intensive task. And this situation is further compounded when you have to let the system run these calculations as a background job or batch process, when there is a CMS reporting deadline and all your users hit the EHR on the last day (yes we have dealt, thankfully rather gracefully with such binge-CQM calculation night outs)!

To alleviate the modeling challenge, a standard has been developed , HQMF or the Health Quality Measures Format. To see how this works, consider one of the CQMs, # CMS156v1/NQF 0018 which reads as:

Percentage of patients 18- 85 years of age who had a diagnosis of hypertension and whose blood pressure was adequately controlled (<140/90 mm-Hg) during the measurement period.

See below the textual descriptions of this measure (the first figure) and the corresponding HQMF version in the second figure (click on the image to view at full resolution)


The textual description of the various numerator and denominators in the calculation logic


Corresponding HQMF model for just the numerator portion

The next challenge is to write a “translator” that converts HQMFs as queries on the underlying EHR database technology (SQL Server, Oracle or MySQL) so that it corresponds to the DB schema. And you as you go about mapping these queries to your DB schema, you also realize that CQM necessitate cross-patient queries, a transactional database might not scale up to support such queries. A separate Clinical Data Warehouse (CDW) would be required which is optimized for CQM queries. A challenge with CDW is to maintain a sync of data between transactional DB and the warehouse to enable near real time query on patient data.


The Office of National Coordinator on Health Information Technology (ONC) started a project, popHealth, an open source reference implementation to automate the Meaningful Use measures calculation. The core popHealth technology has a nice architecture, is scalable, and uses state-of-the-art tools. There are 3 main components as shown in the diagram below:


The PopHealth Architecture and related components.

  1. popHealth App: The  popHealth codebase ( is a Ruby-on-Rails app that provides the front end to create users, upload CCDAs, and a sleek, user-friendly UI to show the metric calculations. The UI also enables downloading calculation results as QRDA-I and QRDA-III XML files. This code is structured as a standard Model-View-Controller paradigm and uses Coffescript (a nicer way to write Javascript) for all the asynchronous aspects of the UI.
  2. Health Data Standards: This module of the architecture ( is a separate Ruby codebase that models the underlying clinical data (Patient, Provider, Labs, Allergies and so on) and the measure related data models. It also contains the parsers for CCDA and generators for QRDAs.
  3. Quality Measure Engine: This component ( is the calculating engine that runs the actual measures using a MapReduce paradigm over MongoDB.

Note that Health Data Standards and Quality Measure Engine are the same tools used by the Cypress test tool used during the certification process. Hence, the advantage of using popHealth is that you are almost guaranteed to pass the certification as it uses the same underlying components.

To deal with future versions of Meaningful Use Stage 2 and Stage 3, it’s as simple as dropping the latest measure-bundle from the ONC.

popHealth EHR Integration Challenges

The popHealth as a standalone reference implementation is a great piece of technology. However, once you try to integrate it with a real-world EHR then things start going downhill quickly. Below are some of the immediate set of challenges encountered:

  • One of the biggest limitations in popHealth v2.1 is the lack of an API to push data and retrieve measures (although the newer versions have added this, but it’s still severely limited).
  • The popHealth architecture assumes that it will be run for a single practice and hence it calculates measures over all patient records available. If any EHR intends to use it then it would need to support separate measure calculations specific to a provider or a group of providers (who can be part of a single practice or a company); this can be very challenging to do within popHealth directly.
  • Some sort of single-sign on capability is needed to enable EHR users to view the measures on the sleek/modern popHealth UI (though the measures could also be pulled into EHR interface for viewing).
  • Add capability to indicate some form of ETA on calculations.
  • Enable a bulk import functionality to import patient records and maintain a sync between the EHR and popHealth.
  • Allow partial/”diff-only” imports of patient records. This becomes critical when a group of patient records are very large in size and cause the importers to clog.
  • Scaling to run calculations over millions of patient records with varying levels of service demands.

There are numerous other minor set of challenges such as customizing the views for EH (Eligible Hospital) versus EP (Eligible Practitioner), date filters to support 90 day reports (required by CMS for first time submitters), adding EHR vendor certification IDs in the QRDAs and so on. As you can see, building this functionality for your EHR user base is not a trivial task.

popEYE – A RESTful API on popHealth

To overcome the challenges mentioned above, we worked on building, refining and implementing popEYE,  a CQM RESTful APIthat can be used to tie any EHR to the underlying popHealth system. the first iteration of popEYE was used to build an App over popHealth that would allow providers to send reminders to different cohorts of numerators and denominators for different preventive service utilization. This App won the best popHealth App award from the ONC, the prize being literally announced and handed by the then head of the ONC, Farzad.

The idea of the popEYE REST API is to provide a simple set of endpoints to perform various operations to interact bi-directionally with EHR interface seamlessly. Some of the sample calls below give an idea of REST API over popHealth (move to the right in the box to see the full snippet):

POST /pophealth//patients: Create a new patient record under the given tenant.
PUT /pophealth//patients: Edit an existing patient record with the "diff" data
POST /pophealth//patients/bulk: Create a bunch of patient records in a single operation
GET /pophealth//measures: Get all the measures for a given tenant
GET /pophealth//measures/: Get counts for a specific measure
POST /pophealth//measures/calc: Start the background calculation job for a tentant
GET /pophealth//measures/calc//status: Get the status on the background calculation job

We had to make tweaks at various places to pass Cypress tests suite and also modules to add additional importers for missing data. We had to change the underlying data model and internal code to support multi-tenancy (multi-practice). We also integrated SAML 2.0 to use a single sign on integration with EHR. A JSON data model was developed to allow exchange of patient record data between EHR and popHealth system.

The biggest set of challenges we faced were in scaling the backend to support varying levels of demands and operate over millions of records. I will discuss our scaling strategies in future blogs. Stay tuned!

Don’t hesitate to reach out to me if you have questions and need help in setting up the popEYE CQM API over popHealth in your own environment.

Share this article

Chintan brings in more than 15 years experience as a Computer Scientist and Biomedical Informatician. At Applied Informatics, he builds stuff with funny acronyms such as REST, API, JSON, JSX, RDF and so on. His areas of expertise include software architecture, semantic technologies, biomedical ontologies, machine learning and natural language processing. Previously, he worked at IBM’s T.J. Watson Research, on ontology-reasoning and information extraction that then became the infamous Jeopardy winning AI software “Watson”. He holds a Ph.D. (Hons) in Biomedical Informatics from Columbia University.

Facebook Comments