From 60d7340daa2d9c441521bed498751541dee99091 Mon Sep 17 00:00:00 2001 From: GAlemsky Date: Tue, 10 Nov 2026 14:57:28 +0600 Subject: [PATCH 1/9] eRx: document the EPCS practitioner log Co-Authored-By: Claude Opus 5.5 --- SUMMARY.md | 1 + docs/modules/eprescription/epcs/README.md | 1 + .../eprescription/epcs/practitioner-log.md | 155 ++++++++++++++++++ 3 files changed, 157 insertions(+) create mode 100644 docs/modules/eprescription/epcs/practitioner-log.md diff --git a/SUMMARY.md b/SUMMARY.md index 1309258c5..ed0964599 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -445,6 +445,7 @@ * [List Permissions](modules/eprescription/epcs/access-management/list-permissions.md) * [Access-Change Requests](modules/eprescription/epcs/access-management/access-change-requests.md) * [Location Compliance Status](modules/eprescription/epcs/access-management/location-compliance-status.md) + * [Practitioner Log](modules/eprescription/epcs/practitioner-log.md) * [Directory](modules/eprescription/directory/README.md) * [DirectoryDownload Message](modules/eprescription/directory/directorydownload-message.md) * [GetProviderLocation Message](modules/eprescription/directory/getproviderlocation-message.md) diff --git a/docs/modules/eprescription/epcs/README.md b/docs/modules/eprescription/epcs/README.md index a5a6cf95e..0b24ea683 100644 --- a/docs/modules/eprescription/epcs/README.md +++ b/docs/modules/eprescription/epcs/README.md @@ -9,3 +9,4 @@ The module does not support prescribing controlled substances yet, but we are wo {% endhint %} * [EPCS Access Management](access-management/README.md): appoint the people who manage EPCS access at each location. +* [Practitioner Log](practitioner-log.md): retrieve the controlled prescriptions a practitioner signed in a period. diff --git a/docs/modules/eprescription/epcs/practitioner-log.md b/docs/modules/eprescription/epcs/practitioner-log.md new file mode 100644 index 000000000..22d1a25f9 --- /dev/null +++ b/docs/modules/eprescription/epcs/practitioner-log.md @@ -0,0 +1,155 @@ +--- +description: Retrieve the log of controlled prescriptions a practitioner signed in a period, as JSON or CSV, in the Aidbox ePrescription module. +--- + +# Practitioner Log + +The practitioner log lists the controlled prescriptions one practitioner signed during a period, with the [NewRx](../prescribing/newrx-message.md) and [CancelRx](../prescribing/cancelrx-message.md) outcome of each one. +It provides the log of a requested period that [21 CFR 1311.120(b)(27)](https://www.ecfr.gov/current/title-21/section-1311.120) describes. + +```http +GET /e-prescription/audit/practitioner-log/?from=2026-05-01&to=2026-05-31 +``` + +Query parameters: + +* `from` and `to` (required): the first and the last day of the period, as ISO dates. The period includes both days. +* `format=csv`: returns the log as CSV instead of JSON. +* `refresh=true`: builds the log again, see [Archives and Refresh](#archives-and-refresh). + +The log has one entry for each controlled prescription the practitioner signed in the period. +The module places a prescription in the period by its signing date in UTC, so a prescription written in April and signed in May belongs to May. + +## Values From Signing Time + +Each entry shows these values as the practitioner signed them: + +* patient name +* drug name +* dispense quantity +* location address +* dispensing pharmacy name + +The module saves these values when the practitioner signs the prescription, and the log reads them from that record. +A later change to the `Patient`, `MedicationRequest`, `Location`, or pharmacy `Organization` does not change the log. + +The transmission, callback, timeout, and cancellation statuses come from the prescription's activity after signing, so a [refreshed](#archives-and-refresh) log can show newer statuses. + +## JSON Response + +`200 OK` returns the log: + +```json +{ + "metadata": { + "generatedAt": "2026-06-01T09:15:42.317Z", + "generatorVersion": "v1", + "practitionerId": "pr-12345", + "period": { "from": "2026-05-01", "to": "2026-05-31" }, + "reportKind": "practitioner-log", + "generationMode": "on-demand", + "auditEvents": { "count": 4, "fingerprint": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b" }, + "snapshotDataFingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" + }, + "entries": [ + { + "medicationRequestId": "med-req-7a1c", + "patient": { "id": "pat-3310", "name": "Carter Alice" }, + "medication": { "name": "Adderall 10 MG Oral Tablet" }, + "deaSchedule": "II", + "quantity": { + "value": 60, + "unit": "Tablet", + "code": "C48542", + "system": "urn:app:aidbox:e-prescriptions:ncpdp:QuantityUnitOfMeasure" + }, + "issueDate": "2026-05-08", + "signedAt": "2026-05-08T16:42:03Z", + "selectedDeaNumber": "BJ1234563", + "practitioner": { "id": "pr-12345" }, + "practitionerRole": { "id": "prole-987" }, + "location": { + "id": "loc-55", + "address": { "line": ["123 Main St"], "city": "Springfield", "state": "IL", "postalCode": "62701" } + }, + "pharmacy": { "id": "org-7788", "name": "Springfield Community Pharmacy" }, + "transmissionStatus": "active", + "callbackStatus": "completed", + "reconciliationIdentifiers": { + "prescriberOrderNumber": "PON-2026-000812", + "surescriptsMessageId": "f47ac10b-58cc-4372-a567-0e02b2c3d479" + } + } + ] +} +``` + +`metadata` describes the log: when the module built it, for which practitioner and period, and the fingerprints it compares on [refresh](#archives-and-refresh). + +The module sorts `entries` by patient name, then drug name, then issue date. Each entry holds: + +* `medicationRequestId`: the signed `MedicationRequest`. +* `patient`: the `Patient` id and the signed patient name, as "Family Given". +* `medication.name`: the signed drug name. +* `quantity`: the signed dispense quantity. +* `deaSchedule`: the DEA schedule of the signed prescription. +* `issueDate`: the signing date in UTC. +* `signedAt`: the signing time. +* `selectedDeaNumber`: the DEA number the practitioner signed under. +* `practitioner` and `practitionerRole`: the ids of the signing `Practitioner` and `PractitionerRole`. +* `location`: the `Location` id and the signed location address. +* `pharmacy`: the pharmacy `Organization` id and the signed pharmacy name. +* `transmissionStatus`, `callbackStatus`, and `timeoutStatus`: the latest NewRx statuses. +* `cancellationStatus`: the latest CancelRx status. +* `reconciliationIdentifiers`: the `prescriberOrderNumber` and `surescriptsMessageId` of the NewRx, to match the entry with Surescripts records. + +The module leaves out empty fields, so an entry without a cancellation has no `cancellationStatus`. + +## CSV Response + +With `format=csv`, `200 OK` returns `text/csv` with a header row and one row per entry, in the order of the JSON entries: + +```csv +Patient,Drug Name,Issue Date,Signed Time,DEA Schedule,Quantity,Selected DEA Number,Practitioner Role,Location,Pharmacy,Transmission Status,Callback Status,Timeout Status,Cancellation Status,Prescriber Order Number,Surescripts Message ID,MedicationRequest ID +Carter Alice,Adderall 10 MG Oral Tablet,2026-05-08,2026-05-08T16:42:03Z,II,60 Tablet C48542,BJ1234563,prole-987,loc-55,Springfield Community Pharmacy,active,completed,,,PON-2026-000812,f47ac10b-58cc-4372-a567-0e02b2c3d479,med-req-7a1c +``` + +`Practitioner Role` and `Location` hold ids, and `Pharmacy` holds the signed pharmacy name. + +The `metadata` comes in response headers: + +* `X-Practitioner-Log-Generated-At`: `generatedAt` +* `X-Practitioner-Log-Generator-Version`: `generatorVersion` +* `X-Practitioner-Log-Practitioner-Id`: `practitionerId` +* `X-Practitioner-Log-Period-From` and `X-Practitioner-Log-Period-To`: `period` +* `X-Practitioner-Log-Report-Kind`: `reportKind` +* `X-Practitioner-Log-Generation-Mode`: `generationMode` +* `X-Practitioner-Log-Audit-Events-Count` and `X-Practitioner-Log-Audit-Events-Fingerprint`: `auditEvents` +* `X-Practitioner-Log-Snapshot-Data-Fingerprint`: `snapshotDataFingerprint` + +## Archives and Refresh + +The first request for a practitioner and period builds the log and archives it. +Later requests for the same practitioner and period return the archived log unchanged, in JSON or CSV. + +An archive is a `DocumentReference` with the type code `practitioner-log`, whose attachment points to a `Binary` that holds the log JSON. +The module keeps every archive and never changes one. + +With `refresh=true`, the module builds the log again and compares it with the newest archive: + +* when the module recorded a new `AuditEvent` for a prescription in the log, or the practitioner signed another prescription in the period, it archives the new log and returns it +* otherwise, it returns the newest archive + +A change to a `Patient`, `MedicationRequest`, `Location`, or pharmacy `Organization` after signing does not add an archive, because the log shows the [values from signing time](#values-from-signing-time). + +
+ +Error Responses + +* `422` when any of these is true: + * `from` or `to` is missing + * `from` or `to` is not an ISO date + * `from` is after `to` + * `format` has a value other than `csv` + +
From 63da5cc357bd906b671c974909b4f3e732bcadf8 Mon Sep 17 00:00:00 2001 From: GAlemsky Date: Tue, 10 Nov 2026 15:35:19 +0600 Subject: [PATCH 2/9] eRx: correct the practitioner log status for missing period parameters --- docs/modules/eprescription/epcs/practitioner-log.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/eprescription/epcs/practitioner-log.md b/docs/modules/eprescription/epcs/practitioner-log.md index 22d1a25f9..482c32804 100644 --- a/docs/modules/eprescription/epcs/practitioner-log.md +++ b/docs/modules/eprescription/epcs/practitioner-log.md @@ -146,8 +146,8 @@ A change to a `Patient`, `MedicationRequest`, `Location`, or pharmacy `Organizat Error Responses +* `400` when `from` or `to` is missing * `422` when any of these is true: - * `from` or `to` is missing * `from` or `to` is not an ISO date * `from` is after `to` * `format` has a value other than `csv` From 9c77dca77e608129f923bfafdf1e35e8ded205a7 Mon Sep 17 00:00:00 2001 From: GAlemsky Date: Tue, 10 Nov 2026 16:59:08 +0600 Subject: [PATCH 3/9] eRx: clarify the practitioner log page wording Name the values saved at signing consistently, state what refresh compares, list the CSV columns that hold part of an entry field, and split the refresh conditions into a list. Co-Authored-By: Claude Opus 5.5 --- .../eprescription/epcs/practitioner-log.md | 49 +++++++++++-------- 1 file changed, 28 insertions(+), 21 deletions(-) diff --git a/docs/modules/eprescription/epcs/practitioner-log.md b/docs/modules/eprescription/epcs/practitioner-log.md index 482c32804..a642f11c8 100644 --- a/docs/modules/eprescription/epcs/practitioner-log.md +++ b/docs/modules/eprescription/epcs/practitioner-log.md @@ -4,8 +4,8 @@ description: Retrieve the log of controlled prescriptions a practitioner signed # Practitioner Log -The practitioner log lists the controlled prescriptions one practitioner signed during a period, with the [NewRx](../prescribing/newrx-message.md) and [CancelRx](../prescribing/cancelrx-message.md) outcome of each one. -It provides the log of a requested period that [21 CFR 1311.120(b)(27)](https://www.ecfr.gov/current/title-21/section-1311.120) describes. +The practitioner log lists the controlled prescriptions one practitioner signed during a period, one entry per prescription, with the [NewRx](../prescribing/newrx-message.md) and [CancelRx](../prescribing/cancelrx-message.md) outcome of each one. +[21 CFR 1311.120(b)(27)](https://www.ecfr.gov/current/title-21/section-1311.120) requires an EPCS application to generate this log for a period the practitioner requests. ```http GET /e-prescription/audit/practitioner-log/?from=2026-05-01&to=2026-05-31 @@ -15,14 +15,13 @@ Query parameters: * `from` and `to` (required): the first and the last day of the period, as ISO dates. The period includes both days. * `format=csv`: returns the log as CSV instead of JSON. -* `refresh=true`: builds the log again, see [Archives and Refresh](#archives-and-refresh). +* `refresh=true`: builds the log again (see [Archives and Refresh](#archives-and-refresh)). -The log has one entry for each controlled prescription the practitioner signed in the period. The module places a prescription in the period by its signing date in UTC, so a prescription written in April and signed in May belongs to May. -## Values From Signing Time +## Values Saved at Signing -Each entry shows these values as the practitioner signed them: +When the practitioner signs a controlled prescription, the module saves these values, and the log shows them: * patient name * drug name @@ -30,10 +29,9 @@ Each entry shows these values as the practitioner signed them: * location address * dispensing pharmacy name -The module saves these values when the practitioner signs the prescription, and the log reads them from that record. -A later change to the `Patient`, `MedicationRequest`, `Location`, or pharmacy `Organization` does not change the log. +A later change to the `Patient`, `Medication`, `MedicationRequest`, `Location`, or pharmacy `Organization` does not change the log. -The transmission, callback, timeout, and cancellation statuses come from the prescription's activity after signing, so a [refreshed](#archives-and-refresh) log can show newer statuses. +The transmission, callback, timeout, and cancellation statuses come from the prescription's NewRx and CancelRx messages after signing, so a [refreshed](#archives-and-refresh) log can show newer statuses. ## JSON Response @@ -84,21 +82,22 @@ The transmission, callback, timeout, and cancellation statuses come from the pre } ``` -`metadata` describes the log: when the module built it, for which practitioner and period, and the fingerprints it compares on [refresh](#archives-and-refresh). +`metadata` says when the module built the log and for which practitioner and period. +`auditEvents` counts and fingerprints the `AuditEvent` resources the log reads, and `snapshotDataFingerprint` fingerprints those events together with the values saved at signing. The module sorts `entries` by patient name, then drug name, then issue date. Each entry holds: * `medicationRequestId`: the signed `MedicationRequest`. -* `patient`: the `Patient` id and the signed patient name, as "Family Given". -* `medication.name`: the signed drug name. -* `quantity`: the signed dispense quantity. +* `patient`: the `Patient` id and the patient name at signing, as "Family Given". +* `medication.name`: the drug name at signing. +* `quantity`: the dispense quantity at signing. * `deaSchedule`: the DEA schedule of the signed prescription. * `issueDate`: the signing date in UTC. * `signedAt`: the signing time. * `selectedDeaNumber`: the DEA number the practitioner signed under. * `practitioner` and `practitionerRole`: the ids of the signing `Practitioner` and `PractitionerRole`. -* `location`: the `Location` id and the signed location address. -* `pharmacy`: the pharmacy `Organization` id and the signed pharmacy name. +* `location`: the `Location` id and the location address at signing. +* `pharmacy`: the pharmacy `Organization` id and the pharmacy name at signing. * `transmissionStatus`, `callbackStatus`, and `timeoutStatus`: the latest NewRx statuses. * `cancellationStatus`: the latest CancelRx status. * `reconciliationIdentifiers`: the `prescriberOrderNumber` and `surescriptsMessageId` of the NewRx, to match the entry with Surescripts records. @@ -114,9 +113,14 @@ Patient,Drug Name,Issue Date,Signed Time,DEA Schedule,Quantity,Selected DEA Numb Carter Alice,Adderall 10 MG Oral Tablet,2026-05-08,2026-05-08T16:42:03Z,II,60 Tablet C48542,BJ1234563,prole-987,loc-55,Springfield Community Pharmacy,active,completed,,,PON-2026-000812,f47ac10b-58cc-4372-a567-0e02b2c3d479,med-req-7a1c ``` -`Practitioner Role` and `Location` hold ids, and `Pharmacy` holds the signed pharmacy name. +Some columns hold one part of an entry field: -The `metadata` comes in response headers: +* `Patient`: the patient name +* `Quantity`: the value, unit, and unit code of the dispense quantity +* `Practitioner Role` and `Location`: the ids +* `Pharmacy`: the pharmacy name + +The response headers carry the `metadata` fields: * `X-Practitioner-Log-Generated-At`: `generatedAt` * `X-Practitioner-Log-Generator-Version`: `generatorVersion` @@ -135,12 +139,15 @@ Later requests for the same practitioner and period return the archived log unch An archive is a `DocumentReference` with the type code `practitioner-log`, whose attachment points to a `Binary` that holds the log JSON. The module keeps every archive and never changes one. -With `refresh=true`, the module builds the log again and compares it with the newest archive: +With `refresh=true`, the module builds the log again and compares its `snapshotDataFingerprint` with the newest archive's. +It archives and returns the new log when either is true: + +* the practitioner signed another controlled prescription in the period +* the module recorded a new `AuditEvent` for a prescription in the log -* when the module recorded a new `AuditEvent` for a prescription in the log, or the practitioner signed another prescription in the period, it archives the new log and returns it -* otherwise, it returns the newest archive +Otherwise, it returns the newest archive. -A change to a `Patient`, `MedicationRequest`, `Location`, or pharmacy `Organization` after signing does not add an archive, because the log shows the [values from signing time](#values-from-signing-time). +The log shows the [values saved at signing](#values-saved-at-signing), so a change to a `Patient`, `Medication`, `MedicationRequest`, `Location`, or pharmacy `Organization` after signing does not add an archive.
From 36936b1022cf2213dc8c42f082384ff2dfd3739b Mon Sep 17 00:00:00 2001 From: GAlemsky Date: Tue, 10 Nov 2026 17:29:27 +0600 Subject: [PATCH 4/9] eRx: tighten the practitioner log page wording Co-Authored-By: Claude Opus 5.5 --- .../eprescription/epcs/practitioner-log.md | 28 +++++++++++-------- 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/modules/eprescription/epcs/practitioner-log.md b/docs/modules/eprescription/epcs/practitioner-log.md index a642f11c8..4ca481eac 100644 --- a/docs/modules/eprescription/epcs/practitioner-log.md +++ b/docs/modules/eprescription/epcs/practitioner-log.md @@ -4,7 +4,8 @@ description: Retrieve the log of controlled prescriptions a practitioner signed # Practitioner Log -The practitioner log lists the controlled prescriptions one practitioner signed during a period, one entry per prescription, with the [NewRx](../prescribing/newrx-message.md) and [CancelRx](../prescribing/cancelrx-message.md) outcome of each one. +The **practitioner log** lists the controlled prescriptions one practitioner signed during a period, one entry per prescription. +Each entry also shows the latest [NewRx](../prescribing/newrx-message.md) and [CancelRx](../prescribing/cancelrx-message.md) statuses of its prescription. [21 CFR 1311.120(b)(27)](https://www.ecfr.gov/current/title-21/section-1311.120) requires an EPCS application to generate this log for a period the practitioner requests. ```http @@ -13,7 +14,7 @@ GET /e-prescription/audit/practitioner-log/?from=2026-05-01&to= Query parameters: -* `from` and `to` (required): the first and the last day of the period, as ISO dates. The period includes both days. +* `from` and `to` (required): the first and the last day of the period, as ISO dates. * `format=csv`: returns the log as CSV instead of JSON. * `refresh=true`: builds the log again (see [Archives and Refresh](#archives-and-refresh)). @@ -83,11 +84,13 @@ The transmission, callback, timeout, and cancellation statuses come from the pre ``` `metadata` says when the module built the log and for which practitioner and period. -`auditEvents` counts and fingerprints the `AuditEvent` resources the log reads, and `snapshotDataFingerprint` fingerprints those events together with the values saved at signing. +`auditEvents` counts and fingerprints the `AuditEvent` resources the log reads. +`snapshotDataFingerprint` fingerprints those events together with the values saved at signing. -The module sorts `entries` by patient name, then drug name, then issue date. Each entry holds: +The module sorts `entries` by patient name, then drug name, then issue date. +Each entry holds: -* `medicationRequestId`: the signed `MedicationRequest`. +* `medicationRequestId`: the id of the signed `MedicationRequest`. * `patient`: the `Patient` id and the patient name at signing, as "Family Given". * `medication.name`: the drug name at signing. * `quantity`: the dispense quantity at signing. @@ -113,7 +116,7 @@ Patient,Drug Name,Issue Date,Signed Time,DEA Schedule,Quantity,Selected DEA Numb Carter Alice,Adderall 10 MG Oral Tablet,2026-05-08,2026-05-08T16:42:03Z,II,60 Tablet C48542,BJ1234563,prole-987,loc-55,Springfield Community Pharmacy,active,completed,,,PON-2026-000812,f47ac10b-58cc-4372-a567-0e02b2c3d479,med-req-7a1c ``` -Some columns hold one part of an entry field: +Some columns hold only part of an entry field: * `Patient`: the patient name * `Quantity`: the value, unit, and unit code of the dispense quantity @@ -134,18 +137,19 @@ The response headers carry the `metadata` fields: ## Archives and Refresh The first request for a practitioner and period builds the log and archives it. -Later requests for the same practitioner and period return the archived log unchanged, in JSON or CSV. +Later requests for the same practitioner and period return the log from the newest archive unchanged, in JSON or CSV. An archive is a `DocumentReference` with the type code `practitioner-log`, whose attachment points to a `Binary` that holds the log JSON. The module keeps every archive and never changes one. -With `refresh=true`, the module builds the log again and compares its `snapshotDataFingerprint` with the newest archive's. -It archives and returns the new log when either is true: +With `refresh=true`, the module builds the log again. +It archives and returns the new log when its `snapshotDataFingerprint` differs from the newest archive's. +The fingerprint changes when either is true: * the practitioner signed another controlled prescription in the period * the module recorded a new `AuditEvent` for a prescription in the log -Otherwise, it returns the newest archive. +Otherwise, it returns the log from the newest archive. The log shows the [values saved at signing](#values-saved-at-signing), so a change to a `Patient`, `Medication`, `MedicationRequest`, `Location`, or pharmacy `Organization` after signing does not add an archive. @@ -153,8 +157,8 @@ The log shows the [values saved at signing](#values-saved-at-signing), so a chan Error Responses -* `400` when `from` or `to` is missing -* `422` when any of these is true: +* `400`: `from` or `to` is missing. +* `422`: any of these is true: * `from` or `to` is not an ISO date * `from` is after `to` * `format` has a value other than `csv` From 0d3728998eb78ff8b3c348815edf27860d8e0962 Mon Sep 17 00:00:00 2001 From: GAlemsky Date: Tue, 10 Nov 2026 20:22:10 +0600 Subject: [PATCH 5/9] eRx: name the issued values and list the refresh outcomes on the practitioner log page Co-Authored-By: Claude Opus 5.5 --- .../eprescription/epcs/practitioner-log.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/modules/eprescription/epcs/practitioner-log.md b/docs/modules/eprescription/epcs/practitioner-log.md index 4ca481eac..5e641592e 100644 --- a/docs/modules/eprescription/epcs/practitioner-log.md +++ b/docs/modules/eprescription/epcs/practitioner-log.md @@ -20,14 +20,14 @@ Query parameters: The module places a prescription in the period by its signing date in UTC, so a prescription written in April and signed in May belongs to May. -## Values Saved at Signing +## Issued Values -When the practitioner signs a controlled prescription, the module saves these values, and the log shows them: +When the practitioner signs a controlled prescription, the module saves its **issued values**, and the log shows them: * patient name * drug name * dispense quantity -* location address +* address of the prescribing location * dispensing pharmacy name A later change to the `Patient`, `Medication`, `MedicationRequest`, `Location`, or pharmacy `Organization` does not change the log. @@ -85,7 +85,7 @@ The transmission, callback, timeout, and cancellation statuses come from the pre `metadata` says when the module built the log and for which practitioner and period. `auditEvents` counts and fingerprints the `AuditEvent` resources the log reads. -`snapshotDataFingerprint` fingerprints those events together with the values saved at signing. +`snapshotDataFingerprint` fingerprints those events together with the issued values. The module sorts `entries` by patient name, then drug name, then issue date. Each entry holds: @@ -142,16 +142,17 @@ Later requests for the same practitioner and period return the log from the newe An archive is a `DocumentReference` with the type code `practitioner-log`, whose attachment points to a `Binary` that holds the log JSON. The module keeps every archive and never changes one. -With `refresh=true`, the module builds the log again. -It archives and returns the new log when its `snapshotDataFingerprint` differs from the newest archive's. +With `refresh=true`, the module builds the log again and compares its `snapshotDataFingerprint` with the newest archive's: + +* The fingerprints differ: the module archives the new log and returns it. +* The fingerprints match: the module returns the log from the newest archive. + The fingerprint changes when either is true: * the practitioner signed another controlled prescription in the period * the module recorded a new `AuditEvent` for a prescription in the log -Otherwise, it returns the log from the newest archive. - -The log shows the [values saved at signing](#values-saved-at-signing), so a change to a `Patient`, `Medication`, `MedicationRequest`, `Location`, or pharmacy `Organization` after signing does not add an archive. +An edit to the prescription's resources after signing does not change the fingerprint, because the log shows the [issued values](#issued-values).
From d946cb59bddcbd36248b89320ae630e778e9ca91 Mon Sep 17 00:00:00 2001 From: GAlemsky Date: Tue, 10 Nov 2026 20:52:58 +0600 Subject: [PATCH 6/9] eRx: tell deployers to restrict the practitioner log route with an AccessPolicy Co-Authored-By: Claude Opus 5.5 --- .../eprescription/epcs/practitioner-log.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/modules/eprescription/epcs/practitioner-log.md b/docs/modules/eprescription/epcs/practitioner-log.md index 5e641592e..f6ce909d1 100644 --- a/docs/modules/eprescription/epcs/practitioner-log.md +++ b/docs/modules/eprescription/epcs/practitioner-log.md @@ -20,6 +20,31 @@ Query parameters: The module places a prescription in the period by its signing date in UTC, so a prescription written in April and signed in May belongs to May. +## Access Policy + +The module does not check who calls this route. +It returns any practitioner's log to any request that your AccessPolicies allow. + +Write an AccessPolicy that allows this route only to the people who may read a practitioner's log, typically the practitioner themselves. +[Configure Access Policies](access-management/configure-access-policies.md) shows how to write policies for the EPCS routes. + +This example policy lets a user read only their own log. +It requires the route's `practitioner-id` to be the id of the `Practitioner` that the user's `User.fhirUser` references: + +```yaml +resourceType: AccessPolicy +id: erx-epcs-practitioner-log-own +engine: matcho +matcho: + uri: '#/e-prescription/audit/practitioner-log/.*' + request-method: get + user: + fhirUser: + resourceType: Practitioner + params: + practitioner-id: .user.fhirUser.id +``` + ## Issued Values When the practitioner signs a controlled prescription, the module saves its **issued values**, and the log shows them: From 02413dd8b0d20beca391cb65b28d4461274cd90d Mon Sep 17 00:00:00 2001 From: GAlemsky Date: Wed, 18 Nov 2026 17:58:32 +0600 Subject: [PATCH 7/9] eRx: trim the practitioner log page and collapse its examples Co-Authored-By: Claude Opus 5.5 --- .../eprescription/epcs/practitioner-log.md | 119 ++++++++++-------- 1 file changed, 68 insertions(+), 51 deletions(-) diff --git a/docs/modules/eprescription/epcs/practitioner-log.md b/docs/modules/eprescription/epcs/practitioner-log.md index f6ce909d1..ac8ae470e 100644 --- a/docs/modules/eprescription/epcs/practitioner-log.md +++ b/docs/modules/eprescription/epcs/practitioner-log.md @@ -5,7 +5,6 @@ description: Retrieve the log of controlled prescriptions a practitioner signed # Practitioner Log The **practitioner log** lists the controlled prescriptions one practitioner signed during a period, one entry per prescription. -Each entry also shows the latest [NewRx](../prescribing/newrx-message.md) and [CancelRx](../prescribing/cancelrx-message.md) statuses of its prescription. [21 CFR 1311.120(b)(27)](https://www.ecfr.gov/current/title-21/section-1311.120) requires an EPCS application to generate this log for a period the practitioner requests. ```http @@ -16,35 +15,15 @@ Query parameters: * `from` and `to` (required): the first and the last day of the period, as ISO dates. * `format=csv`: returns the log as CSV instead of JSON. -* `refresh=true`: builds the log again (see [Archives and Refresh](#archives-and-refresh)). +* `refresh=true`: builds the log again (see [Refresh](#refresh)). The module places a prescription in the period by its signing date in UTC, so a prescription written in April and signed in May belongs to May. ## Access Policy -The module does not check who calls this route. -It returns any practitioner's log to any request that your AccessPolicies allow. - -Write an AccessPolicy that allows this route only to the people who may read a practitioner's log, typically the practitioner themselves. +The module returns any practitioner's log to any request your AccessPolicies allow, so write a policy that allows this route only to the users who may read the log. [Configure Access Policies](access-management/configure-access-policies.md) shows how to write policies for the EPCS routes. -This example policy lets a user read only their own log. -It requires the route's `practitioner-id` to be the id of the `Practitioner` that the user's `User.fhirUser` references: - -```yaml -resourceType: AccessPolicy -id: erx-epcs-practitioner-log-own -engine: matcho -matcho: - uri: '#/e-prescription/audit/practitioner-log/.*' - request-method: get - user: - fhirUser: - resourceType: Practitioner - params: - practitioner-id: .user.fhirUser.id -``` - ## Issued Values When the practitioner signs a controlled prescription, the module saves its **issued values**, and the log shows them: @@ -57,11 +36,15 @@ When the practitioner signs a controlled prescription, the module saves its **is A later change to the `Patient`, `Medication`, `MedicationRequest`, `Location`, or pharmacy `Organization` does not change the log. -The transmission, callback, timeout, and cancellation statuses come from the prescription's NewRx and CancelRx messages after signing, so a [refreshed](#archives-and-refresh) log can show newer statuses. +The transmission, callback, timeout, and cancellation statuses come from the prescription's [NewRx](../prescribing/newrx-message.md) and [CancelRx](../prescribing/cancelrx-message.md) messages after signing, so a [refreshed](#refresh) log can show newer statuses. ## JSON Response -`200 OK` returns the log: +Without `format`, `200 OK` returns the log as JSON. + +
+ +Response ```json { @@ -108,45 +91,29 @@ The transmission, callback, timeout, and cancellation statuses come from the pre } ``` +
+ `metadata` says when the module built the log and for which practitioner and period. `auditEvents` counts and fingerprints the `AuditEvent` resources the log reads. `snapshotDataFingerprint` fingerprints those events together with the issued values. The module sorts `entries` by patient name, then drug name, then issue date. -Each entry holds: - -* `medicationRequestId`: the id of the signed `MedicationRequest`. -* `patient`: the `Patient` id and the patient name at signing, as "Family Given". -* `medication.name`: the drug name at signing. -* `quantity`: the dispense quantity at signing. -* `deaSchedule`: the DEA schedule of the signed prescription. -* `issueDate`: the signing date in UTC. -* `signedAt`: the signing time. -* `selectedDeaNumber`: the DEA number the practitioner signed under. -* `practitioner` and `practitionerRole`: the ids of the signing `Practitioner` and `PractitionerRole`. -* `location`: the `Location` id and the location address at signing. -* `pharmacy`: the pharmacy `Organization` id and the pharmacy name at signing. -* `transmissionStatus`, `callbackStatus`, and `timeoutStatus`: the latest NewRx statuses. -* `cancellationStatus`: the latest CancelRx status. -* `reconciliationIdentifiers`: the `prescriberOrderNumber` and `surescriptsMessageId` of the NewRx, to match the entry with Surescripts records. - The module leaves out empty fields, so an entry without a cancellation has no `cancellationStatus`. ## CSV Response -With `format=csv`, `200 OK` returns `text/csv` with a header row and one row per entry, in the order of the JSON entries: +With `format=csv`, `200 OK` returns `text/csv` with a header row and one row per entry, in the order of the JSON entries. + +
+ +Response ```csv Patient,Drug Name,Issue Date,Signed Time,DEA Schedule,Quantity,Selected DEA Number,Practitioner Role,Location,Pharmacy,Transmission Status,Callback Status,Timeout Status,Cancellation Status,Prescriber Order Number,Surescripts Message ID,MedicationRequest ID Carter Alice,Adderall 10 MG Oral Tablet,2026-05-08,2026-05-08T16:42:03Z,II,60 Tablet C48542,BJ1234563,prole-987,loc-55,Springfield Community Pharmacy,active,completed,,,PON-2026-000812,f47ac10b-58cc-4372-a567-0e02b2c3d479,med-req-7a1c ``` -Some columns hold only part of an entry field: - -* `Patient`: the patient name -* `Quantity`: the value, unit, and unit code of the dispense quantity -* `Practitioner Role` and `Location`: the ids -* `Pharmacy`: the pharmacy name +
The response headers carry the `metadata` fields: @@ -159,14 +126,64 @@ The response headers carry the `metadata` fields: * `X-Practitioner-Log-Audit-Events-Count` and `X-Practitioner-Log-Audit-Events-Fingerprint`: `auditEvents` * `X-Practitioner-Log-Snapshot-Data-Fingerprint`: `snapshotDataFingerprint` -## Archives and Refresh +## Archives The first request for a practitioner and period builds the log and archives it. Later requests for the same practitioner and period return the log from the newest archive unchanged, in JSON or CSV. -An archive is a `DocumentReference` with the type code `practitioner-log`, whose attachment points to a `Binary` that holds the log JSON. The module keeps every archive and never changes one. +
+ +Archive DocumentReference + +The attachment points to the `Binary` that holds the log JSON. + +```json +{ + "resourceType": "DocumentReference", + "id": "practitioner-log-1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", + "status": "current", + "docStatus": "final", + "type": { + "coding": [{ "system": "urn:app:aidbox:e-prescriptions", "code": "practitioner-log" }] + }, + "subject": { "reference": "Practitioner/pr-12345" }, + "date": "2026-06-01T09:15:42.317Z", + "context": { "period": { "start": "2026-05-01", "end": "2026-05-31" } }, + "identifier": [ + { + "system": "urn:app:aidbox:e-prescriptions:practitioner-log:archive-key", + "value": "practitioner-log|on-demand|pr-12345|2026-05-01|2026-05-31" + }, + { + "system": "urn:app:aidbox:e-prescriptions:practitioner-log:generator-version", + "value": "v1" + }, + { + "system": "urn:app:aidbox:e-prescriptions:practitioner-log:audit-events-fingerprint", + "value": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b" + }, + { + "system": "urn:app:aidbox:e-prescriptions:practitioner-log:snapshot-data-fingerprint", + "value": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" + } + ], + "content": [ + { + "attachment": { + "contentType": "application/json", + "url": "Binary/practitioner-log-payload-6f1c2a9e-3d4b-4e8f-9a1b-2c3d4e5f6a7b" + } + } + ] +} +``` + +
+ +### Refresh + With `refresh=true`, the module builds the log again and compares its `snapshotDataFingerprint` with the newest archive's: * The fingerprints differ: the module archives the new log and returns it. From ece2b8c052a65dcb5dc42d272f716e3c0eeffabd Mon Sep 17 00:00:00 2001 From: GAlemsky Date: Wed, 18 Nov 2026 18:01:04 +0600 Subject: [PATCH 8/9] eRx: drop the regulation line from the practitioner log intro Co-Authored-By: Claude Opus 5.5 --- docs/modules/eprescription/epcs/practitioner-log.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/modules/eprescription/epcs/practitioner-log.md b/docs/modules/eprescription/epcs/practitioner-log.md index ac8ae470e..8f93e69fd 100644 --- a/docs/modules/eprescription/epcs/practitioner-log.md +++ b/docs/modules/eprescription/epcs/practitioner-log.md @@ -5,7 +5,7 @@ description: Retrieve the log of controlled prescriptions a practitioner signed # Practitioner Log The **practitioner log** lists the controlled prescriptions one practitioner signed during a period, one entry per prescription. -[21 CFR 1311.120(b)(27)](https://www.ecfr.gov/current/title-21/section-1311.120) requires an EPCS application to generate this log for a period the practitioner requests. +Each entry also shows the latest [NewRx](../prescribing/newrx-message.md) and [CancelRx](../prescribing/cancelrx-message.md) statuses of its prescription. ```http GET /e-prescription/audit/practitioner-log/?from=2026-05-01&to=2026-05-31 @@ -36,7 +36,7 @@ When the practitioner signs a controlled prescription, the module saves its **is A later change to the `Patient`, `Medication`, `MedicationRequest`, `Location`, or pharmacy `Organization` does not change the log. -The transmission, callback, timeout, and cancellation statuses come from the prescription's [NewRx](../prescribing/newrx-message.md) and [CancelRx](../prescribing/cancelrx-message.md) messages after signing, so a [refreshed](#refresh) log can show newer statuses. +The transmission, callback, timeout, and cancellation statuses come from the prescription's NewRx and CancelRx messages after signing, so a [refreshed](#refresh) log can show newer statuses. ## JSON Response @@ -44,7 +44,7 @@ Without `format`, `200 OK` returns the log as JSON.
-Response +Response example ```json { @@ -106,7 +106,7 @@ With `format=csv`, `200 OK` returns `text/csv` with a header row and one row per
-Response +Response example ```csv Patient,Drug Name,Issue Date,Signed Time,DEA Schedule,Quantity,Selected DEA Number,Practitioner Role,Location,Pharmacy,Transmission Status,Callback Status,Timeout Status,Cancellation Status,Prescriber Order Number,Surescripts Message ID,MedicationRequest ID From f04e905d3c0b758c1929cd2ba3763359aec0914a Mon Sep 17 00:00:00 2001 From: GAlemsky Date: Wed, 18 Nov 2026 18:03:15 +0600 Subject: [PATCH 9/9] eRx: drop the statuses line from the practitioner log intro Co-Authored-By: Claude Opus 5.5 --- docs/modules/eprescription/epcs/practitioner-log.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/modules/eprescription/epcs/practitioner-log.md b/docs/modules/eprescription/epcs/practitioner-log.md index 8f93e69fd..199a72148 100644 --- a/docs/modules/eprescription/epcs/practitioner-log.md +++ b/docs/modules/eprescription/epcs/practitioner-log.md @@ -5,7 +5,6 @@ description: Retrieve the log of controlled prescriptions a practitioner signed # Practitioner Log The **practitioner log** lists the controlled prescriptions one practitioner signed during a period, one entry per prescription. -Each entry also shows the latest [NewRx](../prescribing/newrx-message.md) and [CancelRx](../prescribing/cancelrx-message.md) statuses of its prescription. ```http GET /e-prescription/audit/practitioner-log/?from=2026-05-01&to=2026-05-31 @@ -36,7 +35,7 @@ When the practitioner signs a controlled prescription, the module saves its **is A later change to the `Patient`, `Medication`, `MedicationRequest`, `Location`, or pharmacy `Organization` does not change the log. -The transmission, callback, timeout, and cancellation statuses come from the prescription's NewRx and CancelRx messages after signing, so a [refreshed](#refresh) log can show newer statuses. +The transmission, callback, timeout, and cancellation statuses come from the prescription's [NewRx](../prescribing/newrx-message.md) and [CancelRx](../prescribing/cancelrx-message.md) messages after signing, so a [refreshed](#refresh) log can show newer statuses. ## JSON Response