Download the PHP package anun333/oe-module-uds-report without Composer

UDS Report for OpenEMR

This module produces the demographic part of the HRSA Uniform Data System (UDS) report, which every Health Center Program awardee and look-alike files each year. It covers the Patients by ZIP Code table, Tables 3A, 3B and 4, Table 5 (visits and patients by type of service), Table 6A (selected diagnoses and services), and the eCQM lines of Tables 6B and 7 (quality of care and health outcomes, from OpenEMR's own eCQM engine), following the 2026 UDS Manual (calendar year 2026, due February 15, 2027), as the Universal Report and as the Grant Reports for 330(g), (h) and (i) funding. It also lists the patient records that would make the tables wrong, so staff can fix them before submission, and gives whoever prepares Table 9D (patient service revenue) a worksheet from OpenEMR's accounts receivable.

It doesn't submit anything. Health centers still enter the figures in HRSA's Electronic Handbooks (EHBs), and should check them against their own records first.

Status: 0.7.0, pre-release. The counting rules are tested against hand-worked synthetic cases only. They have not yet been compared with a health center's real UDS submission. If your health center uses OpenEMR and would compare this module's table totals with a report you have already filed (totals only, no patient data shared), please open an issue.

What installing it changes in your database, what it reads and writes, and what it hooks into are listed in FOOTPRINT.md, generated from the source.

What it gives you

• Reports › UDS Report: the tables for a chosen year, in the manual's layout and line numbering. Also:
  • a cross-table check (the manual requires the same patient total on every table),
  • a CSV download, and
  • a "Records to fix" list. Blocking problems keep a patient off a table entirely. Quality problems push a patient into an "unknown" line.
• Grant Reports: choose 330(g), 330(h) or 330(i) instead of the Universal Report, on the page and in the CSV. See Grant Reports.
• Table 9D worksheet: charges, collections and adjustments by payer line, reclassified as the manual asks, with each adjustment reason and where it suggests it goes. For staff who can open OpenEMR's Collections report. See Table 9D worksheet.
• eCQM readiness (Tables 6B and 7): whether this OpenEMR can calculate the year's measures, and which records the calculation can't see, with how to fix each. See eCQM readiness.
• Records to fix › patient list: the patients behind each problem, each opening the chart. Viewing the list is written to OpenEMR's audit log.
• Settings (administrators only):
  • which visit categories count as UDS visits,
  • which sites are in the scope of project, school-based, or in or next to public housing,
  • the poverty-guideline region,
  • the UDS insurance category of each insurance company, and
  • the Table 5 line of each provider (suggested from their NUCC taxonomy code) and, optionally, of each visit category.

• Three coded demographic fields, added to the Demographics Stats group:

  • Housing Status (UDS): housed, shelter, transitional, doubling up, street, permanent supportive housing, other homeless arrangement, homeless (arrangement unknown), or declined.
  • Agricultural Worker (UDS): migratory, seasonal, aged or disabled former migratory worker, or declined.
  • Military Service (UDS): served (not on active duty now), active duty, has not served, or declined.

  OpenEMR's own "Homeless" and "Migrant/Seasonal" fields are free text, which the UDS can't use. They are left untouched.

How it counts

Table 5: Staffing and Utilization

Visits (Columns B and B2) and patients (Column C) by type of service and personnel. FTEs (Column A) come from HR records, which OpenEMR doesn't hold, so the column is left for the health center to enter in EHB.

OpenEMR gives every new user the taxonomy code 207Q00000X (Family Medicine). The report flags each provider still on it, and anyone whose code suggests no line, until a line is chosen for them in Settings.

Table 6A: Selected Diagnoses and Services Rendered

Counted from the billing codes on each encounter (the fee sheet's codes). The manual names billing systems and health records as the sources, and its FAQ asks health centers to code a service even when there's no charge, rather than leave it out.

What it can't count yet (each line is marked on the report, with the reason):

• 7 lines defined only by value sets (26c2, 26c3, 38, 39, 40, 41, 42: tobacco cessation drugs, opioid use disorder medications, language assistance, and the upstream drivers of health lines) are left blank. Counting them needs the Value Set Authority Center's expansions.
• 11 lines count the codes the manual lists but not their value sets. On Line 21e (PrEP) the manual also requires a prescription for specific drugs, which isn't checked; on Line 26f (dementia screening) only CPT 99483 counts, not the screeners.
• Codes outside the fee sheet aren't seen: a lab result returned without a billing code, or an immunization recorded only in the Immunizations screen. The manual's preferred fix is to put the code on the encounter with a zero charge.
• Dental Lines 27–32 count the codes whoever recorded them; the manual limits them to dental providers (except fluoride).
• Dental codes are recognised by their shape (D plus four digits) under any code type except ICD, since OpenEMR has no CDT code type.

Grant Reports

A health center funded under more than one Health Center Program type files a Grant Report for each special population it is funded for, alongside the Universal Report (pages 11–12 and 15–16):

Each covers those patients and all their in-scope visits and services, whatever paid for them (FAQ 2), on Tables 3A, 3B, 4, 5 and 6A. Table 5 has no FTEs, and the Patients by ZIP Code table isn't part of a Grant Report. The membership test is the one Table 4 uses, so a Grant Report's total patients equals the Universal Report's line for that population, and no Grant Report cell can be larger than the Universal Report's, as the manual requires.

Table 9D worksheet

Table 9D follows the health center's audited financial statements, and part of it comes from the general ledger (FAQ 8, page 169), so the module gives a worksheet for whoever prepares it, not the table. It reads OpenEMR's accounts receivable: fee sheet charges and the payments and adjustments posted to them. It opens from the Universal Report; Grant Reports have no Table 9D.

Lines 17 and 18, capitation, settlements and wrap payments are left to the general ledger. Insurers not mapped to a UDS category, and insurers mapped to None/Uninsured (a program such as Title X is uninsured on Table 4 but Other Public on Table 9D), get their own rows so the total stays whole. The worksheet also reports payments not yet applied to any visit, and visits paid more than was charged.

eCQM readiness

Most of Tables 6B and 7 are eCQMs, which OpenEMR calculates itself, and the module reports them. Their results are only as good as what the engine can see, so Reports › UDS Report › eCQM readiness shows what to fix first.

It lists the 16 measures UDS 2026 uses (data/ecqm-measures.json), the version the manual names, and whether that version is installed. It also counts, for the year's countable visits and the patients seen at them, the records OpenEMR's eCQM calculation can't see:

Tables 6B and 7

Reports › UDS Report › Tables 6B and 7 shows the eCQM lines of both tables for the year, calculated by OpenEMR's own eCQM engine with the measure versions the manual names, and a CSV download.

Calculating. The engine is run once per year and the results are stored, because it is slow: about a tenth of a second per light synthetic patient, and about a second per patient with realistic records (Synthea patients with years of visits and lab results). 20,000 such patients would take about five and a half hours. An administrator starts it from the page, which works through the patients 50 at a time and can be resumed if closed; for anything but a small health center, run it on the server instead:

Patients the engine refuses. OpenEMR's engine accepts only UCUM units, and one lab result in any other unit (mEq/L, x10E3/uL, IU/L, or the UNK OpenEMR's C-CDA import stores) makes it refuse that patient for every measure. Those patients are left out of every line and named on the page, with the engine's reason, so their records can be corrected and the year calculated again; the CSV gives their number and reasons. The readiness page counts them beforehand, with the UCUM unit for each common one. It also warns when OpenEMR reads lab results as whole numbers, which keeps an HbA1c of 9.4 out of CMS122's poor-control count (it reaches the measure as 9).

What it needs.

• OpenEMR's PHP eCQM engine (openemr/openemr#14469), on OpenEMR master after 8.4.
• The 2026 measure files, in OpenEMR master since 2026-10-13 (openemr/openemr#14536). On an OpenEMR without them, the page names each measure that isn't installed.
• The openemr/openemr#14526: until it's fixed, ongoing problems and visits with no end time don't count, and the page says so.

Not calculated. Line 18 (CMS164v7, which the manual keeps at an old version no measure bundle has); the lines with no eCQM (prenatal care, Lines 1–9; HIV linkage to care, Line 20; dental sealants, Lines 22a and 22b); and Table 7 Section A (deliveries and birth weight). The page lists them, to be reported from the health center's records.

The Financial Review Date pitfall

OpenEMR's Financial Review Date is a plain text box on a date column, and OpenEMR saves with the database's strict checking off. A date typed as 2026-09-15 is kept; typed any other way (9/15/2026, Sept 15) it is silently stored as no date at all, with no message on screen. The patient's income then can't be used and counts as Unknown on Table 4. The Records to fix list names this case on its own ("Financial Review Date was not saved"), so staff can re-enter those dates.

Reference data

The published figures and code mappings are in data/, in plain files that people who prepare UDS submissions can check without reading PHP: the poverty guidelines, the race and ethnicity roll-up, the insurance categories, the Table 5 lines and taxonomy mapping, and the Table 6A codes. The counting rules stay in the code. A broken data file stops the report with a message naming the file and entry; it never runs on a bad edit.

The expected results are data too (data/cases/): line and column placements, insurance categories, poverty thresholds, and whole tables built from synthetic patients worked out by hand from the manual. Any program implementing the same rules can be held to them. The tests run every case (tests/ConformanceTest.php). The full report has also been checked end to end against a running OpenEMR with synthetic patients whose every cell was worked out by hand first.

Not done yet, or approximated

• Other tables: 8A and 9E and the two forms aren't produced yet. Tables 6B and 7 cover their eCQM lines only (above.
• Table 5 FTEs (Column A) aren't computed; they come from HR records. A person who holds two roles (a nurse who is also a case manager, say) has one line per person, plus any line set by visit category.
• Countable visits: whether a visit is truly countable (independent judgment, a credentialed provider, not a nurse-only or ancillary service) is approximated by visit category and provider. Each health center has to set the categories.
• Homelessness and farmworker look-back: the manual counts someone as homeless for 12 months after homelessness was last documented, and as a farmworker if that was their work within 24 months. The module uses the current value of each field; it has no history of past values.
• Medicaid versus CHIP: the two can't be told apart automatically. They're reported as Medicaid unless a plan is set to CHIP in Settings, which is what the manual says to do when they can't be distinguished.
• Validation: tested only with synthetic data. It has not been compared with a health center's real submission.

Install

From the OpenEMR directory:

That places it in interface/modules/custom_modules/oe-module-uds-report/. Then go to Modules › Manage Modules and Register, Install and Enable UDS Report. Installing adds the settings tables and the three demographic fields. Uninstalling leaves them in place, because they hold data staff entered.

Viewing needs patients/demo; the Table 9D worksheet needs acct/rep_a, as OpenEMR's Collections report does; Settings needs admin/super.

Compatibility

PHP 8.3 or later is needed. On 8.1.0 to 8.3.0 the module reads the request itself, because OpenEMR's CurrentRequest only arrived in 8.4.0.

The 8.4.1 checks: Tables 5 and 6A from codes saved through OpenEMR's own billing functions, a Table 5 line chosen through the Settings page, and the Table 9D worksheet from payments and adjustments posted through OpenEMR's EOB posting screen. The eCQM readiness page was also checked against OpenEMR master (c11dd1b15c), where eCQMs are calculated in PHP, with and without a local fix for #14526. Tables 6B and 7 were checked on master (7001d5008b) with #14536's 2026 measures: the module's results for each patient are identical to OpenEMR's own openemr:cqm-calculate, and for 2,009 synthetic patients the CMS165 denominator (1,100) and numerator (443) match what each patient's records predict, by race and ethnicity too, calculated both from the page and from the command line.

The package declares no Composer constraint on openemr/openemr: OpenEMR reports itself to Composer as version 1.0.0+no-version-set, so any minimum version written there would block every install.

Development

License

GPL-3.0-or-later.