Skip to content

Add documentation for Patients with Billable Charge Item and Encounter/Appointment Details query #147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sonzsara wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add documentation for Patients with Billable Charge Item and Encounter/Appointment Details query #147

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions ...patients_with_billable_chargeitem_and_encounter_and_appointment_details_ssmm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@

# Patients with Billable Charge Item and Encounter/Appointment Details - SSMM

> Patient-level list of encounters linked to appointments that have billable charge items

## Purpose

Returns encounter records at SSMM where the linked appointment (`emr_tokenbooking`) has a charge item in `billable` status. The result includes patient details, SSMM identifier, encounter and appointment statuses, charge item status/value, and encounter date.
Comment thread
sonzsara marked this conversation as resolved.

## Parameters

| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `date_filter` | DATE / range | Metabase date filter (typically bound to `emr_encounter.created_date`) | `'2026-08-01'` |
| `encounter_class` | TEXT | Filter by encounter class (exact match on `emr_encounter.encounter_class`) | `'amb'` |
| `encounter_status` | TEXT | Filter by encounter status (exact match on `emr_encounter.status`) | `'in-progress'` |
| `ssmm_id` | TEXT | Filter by patient SSMM identifier value (exact match on `emr_patientidentifier.value`) | `'SSMM-100245'` |

---

## Query

```sql
SELECT
emr_patient.name AS patient_name,
emr_patientidentifier.value AS ssmm_id,
emr_encounter.status AS encounter_status,
emr_encounter.encounter_class AS encounter_class,
emr_tokenbooking.status AS appointment_status,
emr_chargeitem.status AS charge_item_status,
emr_chargeitem.total_price AS total_price,
emr_encounter.created_date AS encounter_date
FROM emr_encounter
JOIN emr_patient
ON emr_patient.id = emr_encounter.patient_id
LEFT JOIN emr_patientidentifier
ON emr_patientidentifier.patient_id = emr_patient.id
AND emr_patientidentifier.config_id = 21
JOIN emr_tokenbooking
ON emr_tokenbooking.associated_encounter_id = emr_encounter.id
JOIN emr_chargeitem
ON emr_chargeitem.id = emr_tokenbooking.charge_item_id
WHERE emr_chargeitem.status = 'billable'

@github-actions github-actions Bot Aug 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Critical] No facility scoping — the _ssmm suffix promises a single-facility query, but nothing in the SQL enforces it.

Facility boundaries are normally enforced by the application, not by Postgres — a raw query has to add it explicitly (care-sql-code-review skill, inversion 2). This query has no facility_id predicate anywhere: not on emr_encounter, not on emr_tokenbooking, not on emr_chargeitem. As written it returns billable charge items across every facility in the deployment, not just SSMM, which is both a wrong-number bug for a per-facility dashboard and a cross-tenant data exposure.

Fix — scope through the encounter (or another table that carries facility_id):

WHERE emr_chargeitem.status = 'billable'
  AND emr_chargeitem.total_price > 0
  AND emr_encounter.facility_id = <ssmm_facility_id>
  ...

If the intent is genuinely "all facilities, but named _ssmm for another reason," please say so in ## Notes — as it stands the filename and the SQL disagree.

AND emr_chargeitem.total_price > 0

@github-actions github-actions Bot Aug 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[High] No entered_in_error / deleted exclusion on any joined table.

emr_chargeitem.status = 'billable' pins the charge item to a valid state, but emr_encounter, emr_tokenbooking, and emr_patientidentifier are joined with no status or deleted filter at all. A mistakenly-created encounter or token booking (status = 'entered_in_error') — or a soft-deleted row (deleted = TRUE) on any of these tables — will still surface in this report with a real billable charge item attached, since the charge item itself can be fine even when the encounter/booking it's linked to is not.

Fix — add per table:

FROM emr_encounter
JOIN emr_patient
	ON emr_patient.id = emr_encounter.patient_id
	AND emr_patient.deleted = FALSE
LEFT JOIN emr_patientidentifier
	ON emr_patientidentifier.patient_id = emr_patient.id
	AND emr_patientidentifier.config_id = 21
	AND emr_patientidentifier.deleted = FALSE
JOIN emr_tokenbooking
	ON emr_tokenbooking.associated_encounter_id = emr_encounter.id
	AND emr_tokenbooking.status != 'entered_in_error'
	AND emr_tokenbooking.deleted = FALSE
JOIN emr_chargeitem
	ON emr_chargeitem.id = emr_tokenbooking.charge_item_id
	AND emr_chargeitem.deleted = FALSE
WHERE emr_chargeitem.status = 'billable'
  AND emr_chargeitem.total_price > 0
  AND emr_encounter.status != 'entered_in_error'
  AND emr_encounter.deleted = FALSE
  ...

(Confirm the exact entered_in_error handling is appropriate for emr_tokenbooking's status enum before applying — worth a quick check against care/emr/resources/scheduling/spec.py if unsure.)

@sonzsara sonzsara Aug 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is already filter for encounter status in the query

@github-actions github-actions Bot Aug 18, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That filter is different from what this finding is about. --[[AND {{encounter_status}}]] is a commented-out optional Metabase parameter — it only fires when a dashboard user picks a specific encounter_status value (e.g. 'in-progress'), and the query runs standalone with it disabled by default. It does not default-exclude entered_in_error, and even when supplied it constrains to one status the user chose, not "not entered_in_error." It also only covers emr_encounter — emr_tokenbooking and emr_patientidentifier still have no status/deleted filter at all, so a mistakenly-created token booking or a soft-deleted identifier can still surface here with a real billable charge item attached.

Suggested fix, alongside the existing optional param:

WHERE emr_chargeitem.status = 'billable'
  AND emr_chargeitem.total_price > 0
  AND emr_encounter.status != 'entered_in_error'
  AND emr_tokenbooking.status != 'entered_in_error'
  --[[AND {{date_filter}}]]
  --[[AND {{encounter_class}}]]
  --[[AND {{encounter_status}}]]
  --[[AND emr_patientidentifier.value = {{ssmm_id}}]]

Leaving this open — the optional param alone doesn't cover it (it's opt-in, single-table, and not an entered_in_error exclusion).

Generated by Analytics SQL Reviewer for #147 · auto · 28.5 AIC · ⌖ 10.2 AIC · ⊞ 14.7K

@sonzsara sonzsara Aug 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

commenting out the filters were intentional

@github-actions github-actions Bot Aug 18, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be clear — I'm not asking you to uncomment --[[AND {{encounter_status}}]] or any of the other optional Metabase params; leaving those commented is the correct repo convention and I'm not flagging it.

The finding is about a different, always-on exclusion that isn't in the query at all: a hardcoded AND emr_encounter.status != 'entered_in_error' (and the equivalent for emr_tokenbooking), which should apply unconditionally regardless of whatever the dashboard user picks for the optional encounter_status filter. Right now nothing excludes entered_in_error rows by default — a mistakenly-created encounter or token booking with a real billable charge item attached will still show up in this report.

If that's an acceptable tradeoff for this report (e.g. entered_in_error rows are rare/negligible at SSMM), that's a reasonable call to make — just flagging so it's a conscious decision rather than an oversight. Leaving this open for your call; happy to resolve if you confirm it's intentional.

Generated by Analytics SQL Reviewer for #147 · auto · 27.4 AIC · ⌖ 3.58 AIC · ⊞ 14.7K

@sonzsara sonzsara Aug 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes didnt add that check because the user wanted to filter using the encounter status filter, it was intentional

@github-actions github-actions Bot Aug 18, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Understood — thanks for confirming. If the intent is to let dashboard users scope out entered_in_error via the optional encounter_status filter rather than hardcoding an always-on exclusion, that's a reasonable, conscious tradeoff (and only leaves emr_tokenbooking uncovered as a known limitation). Resolving.

Generated by Analytics SQL Reviewer for #147 · auto · 24.7 AIC · ⌖ 2.38 AIC · ⊞ 14.7K

--[[AND {{date_filter}}]]
--[[AND {{encounter_class}}]]
--[[AND {{encounter_status}}]]
--[[AND emr_patientidentifier.value = {{ssmm_id}}]]
ORDER BY emr_encounter.created_date DESC, emr_patient.name;
```

@github-actions github-actions Bot Aug 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Medium] Missing ### Output section required by TEMPLATE.md.

The template calls for an ### Output table (column/type/description) directly under ## Query, documenting the 8 selected columns for the dashboard consumer. This doc jumps straight from the SQL fence to ## Notes — please add the output table before merging.


## Notes

- **Core cohort:** Only rows where `emr_chargeitem.status = 'billable'` and `total_price > 0` are included.
- **Identifier mapping:** `config_id = 21` is hardcoded for SSMM patient identifier configuration; update if this mapping changes.

*Last updated: 2026-08-13*
Loading