Care Bundles & Care Gaps
The Care Bundles workbench lets you define measure-based care bundles, materialize population rosters, track compliance over time, and export qualifying cohorts for downstream analysis. Two significant hardening releases shipped on 2026-04-25 that close all known correctness, security, and reliability findings.
Overview
A Care Bundle groups one or more quality measures against a defined population. For each measure, the platform:
- Materializes a roster of qualifying patients from the selected CDM source.
- Evaluates each patient against the measure's numerator/denominator logic.
- Segments the population into compliant, non-compliant, and excluded buckets.
- Tracks trends over successive materialization runs so you can monitor program performance.
Results are available through the Care Bundles UI and via the REST API (/api/v1/care-bundles/...).
Key Concepts
| Term | Description |
|---|---|
| Bundle | A named collection of measures applied to a population cohort. |
| Measure | A single quality metric (numerator/denominator) mapped to OMOP concepts. |
| Roster | The full set of patients evaluated for a measure in one materialization run. |
| Evaluation | The per-patient compliance decision for a given run. |
| Materialization run | A versioned snapshot of compliance results; identified by a run ID. |
| Intersection | A cross-bundle view showing patients who appear in multiple bundles or measures. |
| Overlap rule | A configurable policy that resolves how patients counted in more than one bundle are attributed. |
Creating a Bundle
- Navigate to Care Gaps in the left sidebar (Part VII -- Patient Profiles & Care Gaps).
- Click New Bundle.
- Enter a bundle name and optional description.
- Select the population cohort that defines your denominator universe.
- Add one or more measures. Each measure requires:
- A FHIR Measure reference or a manually configured numerator/denominator concept set.
- An optional overlap rule (default: count patient in the first matching measure).
- Click Save.
Adding Measures
Measures can be sourced from:
- VSAC value sets -- the platform maintains a materialized crosswalk view (
app.vsac_value_set_omop_concepts) that joins VSAC value set OIDs to OMOP standard concepts. - Manual concept sets -- built in the Vocabulary Browser and referenced by concept set ID.
- FHIR Measure resources -- imported via the FHIR EHR Integration module (Part XII).
The VSAC-OMOP crosswalk view requires SELECT privileges on the vocab schema. If you are provisioning a new environment, ensure the database migration 2026_04_24_000050_grant_vocab_select_to_owner.php has been applied. Fresh installations and CI environments that rebuild from migrate:fresh must have this migration in place before the crosswalk view can be created.
Materializing a Bundle
Materialization computes the current roster and evaluations for all measures in a bundle against a selected CDM source.
- Open the bundle and click Materialize.
- Select the CDM source to evaluate against.
- Click Run. The job is queued; progress is visible in the Runs tab.
You can also trigger materialization for all bundles simultaneously using the Materialize All action available to administrators.
Materialization reliability
As of the 2026-04-25 hardening release, materialization is fully crash-safe:
- Roster promotion -- the pointer in
care_bundle_current_runsis updated only after the run's status is set tocompleted. A crash during materialization leaves the previous completed run visible; it never exposes arunning-status run to read queries. - Cohort export atomicity -- the delete-then-insert sequence that writes roster members to the results cohort is now wrapped in a single database transaction. A crash cannot leave the cohort partially replaced.
- Memory-safe chunking -- large non-compliant buckets (for example, 2 M-patient CDMs) are streamed in configurable chunks rather than materialized into PHP heap, preventing out-of-memory failures on wide populations.
Viewing Results
Compliance summary
The Bundle detail page shows, for each measure:
- Denominator count
- Numerator (compliant) count
- Compliance rate (%)
- Trend chart across the last N runs
Stratifications
Use the Strata tab to break results down by age band, sex, or any OMOP-mapped demographic dimension available on the selected CDM source.
Methodology
The Methodology tab documents the exact concept set OIDs, OMOP concept IDs, and SQL logic used for each measure evaluation so results are reproducible and auditable.
Patient-level roster
The Roster tab pages through patients in the non-compliant bucket. Each row shows:
- Person ID (de-identified or mapped, depending on your data governance configuration)
- Inclusion/exclusion criteria met
- Last evaluation date
Roster data is paginated (default 25 rows per page) and can be exported to a Parthenon cohort for further analysis.
Exporting a Roster to a Cohort
- On the Roster tab, click Export to Cohort.
- Choose a cohort name and target cohort definition.
- Click Export.
The export uses a transactional write: the existing cohort members are deleted and the new members are inserted atomically. If the export fails mid-way, the original cohort is preserved intact.
Intersections
The Intersections view shows patients who qualify for measures across multiple bundles. Use this to:
- Identify high-risk patients with multiple care gaps.
- Attribute shared patients according to your configured overlap rules.
- Export a combined cohort for outreach programs.
To compute an intersection:
- Navigate to Intersections within the Care Bundles module.
- Select the bundles to intersect.
- Click Compute Intersection.
- Export to a cohort using Export Intersection to Cohort.
Comparisons
The Comparison view places two bundles side-by-side, showing measure-level compliance rates for the same CDM source and date range. Use this to compare program performance across different populations or time windows.
Coverage & Population Summary
- Coverage -- the fraction of your total CDM population that is captured by at least one bundle denominator.
- Population Summary -- aggregate counts and compliance rates across all bundles, suitable for executive reporting.
Overlap Rules
When a patient qualifies for the denominator of more than one measure, an overlap rule determines how that patient is counted in rollup metrics. Available rules:
| Rule | Behaviour |
|---|---|
| First-match | Patient is attributed to the first measure in bundle order. |
| All | Patient is counted in every qualifying measure (denominator counts may sum > population). |
| Exclude | Patient is excluded from all measures where overlap occurs. |
Overlap rules are configured at the bundle level and can be overridden per measure.
FHIR Measure Integration
Bundles can ingest a FHIR Measure resource to drive numerator/denominator logic. After import:
- The platform extracts the FHIR Measure's population criteria and maps them to OMOP concept sets via the VSAC crosswalk.
- The FHIR Measure is stored and accessible via
GET /api/v1/care-bundles/{bundle}/fhir-measure.
See FHIR EHR Integration for FHIR connection configuration.
API Quick Reference
All Care Bundles endpoints are versioned under /api/v1/care-bundles. Interactive documentation is available in the API section of this manual.
| Method | Path | Description |
|---|---|---|
GET | /care-bundles | List all bundles |
POST | /care-bundles | Create a bundle |
GET | /care-bundles/{bundle} | Get bundle detail |
PUT/PATCH | /care-bundles/{bundle} | Update a bundle |
DELETE | /care-bundles/{bundle} | Delete a bundle |
GET | /care-bundles/{bundle}/measures | List measures in a bundle |
POST | /care-bundles/{bundle}/measures | Add a measure |
DELETE | /care-bundles/{bundle}/measures/{measure} | Remove a measure |
POST | /care-bundles/{bundle}/materialize | Trigger materialization |
POST | /care-bundles/materialize-all | Materialize all bundles |
GET | /care-bundles/{bundle}/runs | List materialization runs |
GET | /care-bundles/runs/{run} | Get run detail |
POST | /care-bundles/{bundle}/evaluate | Trigger evaluation |
GET | /care-bundles/{bundle}/evaluations | List evaluations |
GET | /care-bundles/{bundle}/evaluations/{evaluation} | Get evaluation detail |
GET | /care-bundles/{bundle}/measures/{measure}/roster/{sourceId}/bucket/non-compliant/page/{page} | Page non-compliant roster |
POST | /care-bundles/{bundle}/measures/{measure}/roster/to-cohort | Export roster to cohort |
GET | /care-bundles/{bundle}/measures/{measure}/trend/{sourceId} | Compliance trend data |
GET | /care-bundles/{bundle}/measures/{measure}/strata/{sourceId} | Stratification data |
GET | /care-bundles/{bundle}/measures/{measure}/methodology/{sourceId} | Measure methodology |
GET | /care-bundles/{bundle}/qualifications/{sourceId} | Qualification breakdown |
GET | /care-bundles/{bundle}/comparison | Side-by-side comparison |
GET | /care-bundles/{bundle}/fhir-measure | Retrieve FHIR Measure resource |
GET | /care-bundles/sources | List available CDM sources |
GET | /care-bundles/coverage | Population coverage summary |
GET | /care-bundles/population-summary | Aggregate population stats |
GET | /care-bundles/overlap-rules | List configured overlap rules |
GET | /care-bundles/intersections | List intersections |
POST | /care-bundles/intersections | Compute an intersection |
POST | /care-bundles/intersections/to-cohort | Export intersection to cohort |
Roles & Permissions
| Action | Required Role |
|---|---|
| View bundles and results | care_bundles.view |
| Create / edit bundles | care_bundles.edit |
| Materialize bundles | care_bundles.materialize |
| Export rosters to cohorts | care_bundles.export |
| Delete bundles | care_bundles.delete |
| Materialize all (bulk) | care_bundles.admin |
Roles are assigned in Administration > Roles & Permissions (Part VIII).
Troubleshooting
Materialization fails with a database permission error
If you see SQLSTATE[42501]: permission denied for schema vocab during materialization or on a fresh installation, the vocab schema grant migration has not been applied.
Resolution: Run php artisan migrate and confirm that migration 2026_04_24_000050_grant_vocab_select_to_owner.php appears in the applied list. If you are in a CI or test environment that uses RefreshDatabase, ensure this migration is committed and present before the VSAC crosswalk view migration.
Non-compliant roster appears empty after materialization
- Confirm the measure's concept set contains at least one active OMOP standard concept mapped to the target CDM vocabulary.
- Check the Methodology tab to verify numerator/denominator SQL executed without warnings.
- Review the run log in Runs for any partial-failure messages.
Cohort export overwrites existing members unexpectedly
Cohort export is now atomic (2026-04-25 hardening). If you need to merge rather than replace, export to a new cohort and use the Cohort Management tools (Part III) to union the result.
Trend data shows a gap for a specific run
If promoteToCurrent crashed before the previous release, a run may be in running status permanently. Use the API (GET /care-bundles/runs/{run}) to inspect the run status and contact your administrator to manually mark the run failed so a fresh materialization can proceed.