Implement a CDS Hooks patient-view service that uses a prefetch template to retrieve Observation resources without a server-side FHIR call and returns a gap-in-care card when a required screening is overdue
domain: cds-hooks.org · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
In your CDS service discovery document, define a prefetch object on the patient-view hook service entry with a key such as recentObservations whose value is a FHIR search URL template using the token placeholder for the patient context parameter, scoped to LOINC codes representing the screenings you are tracking
In the hook handler, check whether the prefetch key is populated in the request body; if the EHR honored the prefetch template, the value will be a FHIR Bundle; if it is null or absent, make a direct FHIR server call to the fhirServer base URL provided in the hook request using the fhirAuthorization token
Evaluate each returned Observation's effective date against the recommended screening interval for the patient's age and risk category; compute whether the most recent result falls within the required window
If a gap is detected, construct a CDS Hooks card with indicator info and a detailed summary, and include a link action with a type of absolute pointing to the clinical guideline or smart form URL for ordering the overdue screening
Attach a source object referencing the clinical guideline that defines the screening interval, such as a USPSTF recommendation, so the clinician can distinguish EHR-vendor cards from guideline-backed alerts
Return an empty suggestions array and no system actions if the screening is current so that the EHR does not display a card and alarm fatigue is minimized
Known gotchas
The EHR may choose not to execute the prefetch template and will instead send a null value for the prefetch key; a hook service that throws an error when the prefetch is absent will be disabled by the EHR after repeated failures rather than gracefully falling back to a direct FHIR query
LOINC codes for the same screening test vary by collection method and panel; a prefetch query scoped to a single LOINC code may miss results coded under an equivalent but different LOINC, producing false gap alerts for patients who were actually screened
Patient-view fires every time a chart is opened, including by staff opening the chart for scheduling or billing purposes; returning cards that require clinician action every time the chart opens regardless of who opened it causes alert fatigue and hook bypass
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?