From 4068e5d6fe0b1c78534dbf7b58e5bfe95aff80fb Mon Sep 17 00:00:00 2001 From: GAlemsky Date: Thu, 19 Nov 2026 13:50:13 +0600 Subject: [PATCH 1/2] eRx: document how to enable EPCS Co-Authored-By: Claude Opus 5.5 --- SUMMARY.md | 1 + docs/modules/eprescription/epcs/README.md | 1 + .../modules/eprescription/epcs/enable-epcs.md | 58 +++++++++++++++++++ .../reference/environment-variables.md | 5 ++ 4 files changed, 65 insertions(+) create mode 100644 docs/modules/eprescription/epcs/enable-epcs.md diff --git a/SUMMARY.md b/SUMMARY.md index ed0964599..e602a94f3 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -439,6 +439,7 @@ * [DetectedIssue](modules/eprescription/prescribing/detected-issue.md) * [How to test Callback](modules/eprescription/prescribing/how-to-test-callback.md) * [EPCS](modules/eprescription/epcs/README.md) + * [Enable EPCS](modules/eprescription/epcs/enable-epcs.md) * [EPCS Access Management](modules/eprescription/epcs/access-management/README.md) * [Configure Access Policies](modules/eprescription/epcs/access-management/configure-access-policies.md) * [Bootstrap the First Administrator](modules/eprescription/epcs/access-management/bootstrap-the-first-administrator.md) diff --git a/docs/modules/eprescription/epcs/README.md b/docs/modules/eprescription/epcs/README.md index 0b24ea683..a44bf4ffc 100644 --- a/docs/modules/eprescription/epcs/README.md +++ b/docs/modules/eprescription/epcs/README.md @@ -8,5 +8,6 @@ description: Electronic Prescribing of Controlled Substances (EPCS) in the Aidbo The module does not support prescribing controlled substances yet, but we are working on it. {% endhint %} +* [Enable EPCS](enable-epcs.md): configure the module and your EHR so that prescribers can sign controlled prescriptions. * [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/enable-epcs.md b/docs/modules/eprescription/epcs/enable-epcs.md new file mode 100644 index 000000000..55ab073c7 --- /dev/null +++ b/docs/modules/eprescription/epcs/enable-epcs.md @@ -0,0 +1,58 @@ +--- +description: Configure the Aidbox ePrescription module and your EHR so that prescribers can sign controlled prescriptions. +--- + +# Enable EPCS + +After this setup, a prescriber can mark a controlled prescription ready to sign and sign it only while they hold the EPCS prescribing permission at the prescription's location. +[Prescribing Controlled Substances](access-management/README.md#prescribing-controlled-substances) lists every check the module runs for these two steps. + +## Configure the Module + +1. Set `EPCS_MODE` to `full`. + With the default `disabled`, the module refuses controlled prescriptions. +2. Set `EPCS_PROOF_SECRET` to the output of `openssl rand -hex 32`, a random 64-character string. + The module uses it to detect a change to a controlled prescription between marking it ready to sign and signing it. + If you change the secret later, mark the prescriptions that are already ready to sign again before signing them. +3. Open `App/ePrescription-app` in the Aidbox console (`/ui/console#/entities/App`) and copy the value of `endpoint.secret`. + Aidbox authenticates every call it forwards to the module with this secret. + If it is empty or still `PUT_ENDPOINT_SECRET_HERE`, set it to the output of `openssl rand -hex 32` and save the App. +4. Set `AIDBOX_RPC_CREDENTIALS` to `base64("ePrescription-app:")`. + While it does not match `endpoint.secret`, the module answers every call from Aidbox with `401`, not only the EPCS calls. +5. Restart the module. + +## Call the Module as the Signed-In User + +1. Send each call that marks a prescription ready to sign, signs it, or manages EPCS access with the signed-in person's Aidbox authentication. + The module then gets an [acting user](access-management/configure-access-policies.md#acting-user) for the call. + A call made with only a `Client` credential has no acting user, and the module rejects it. +2. Write AccessPolicies that let your users call these operations: + * `POST /e-prescription/rx/ready-to-sign`, which marks a prescription ready to sign + * `POST /e-prescription/rx/new`, `POST /e-prescription/rx/respond-to-renewal`, and `POST /e-prescription/rx/respond-to-change`, which sign prescriptions + * the EPCS access operations that [Configure Access Policies](access-management/configure-access-policies.md#access-policies) lists + +## Appoint the Access Managers + +Each location where practitioners prescribe controlled substances needs an administrator and an approver who are different users: + +1. Appoint the administrator with [Bootstrap the First Administrator](access-management/bootstrap-the-first-administrator.md). +2. The administrator nominates the approver with an [access-change request](access-management/access-change-requests.md#request-a-change), and the nominee accepts it as the [first approver](access-management/access-change-requests.md#first-approver). +3. Check that [Location Compliance Status](access-management/location-compliance-status.md) returns `compliant: true` for the location. + +## Grant the Prescribing Permission + +For each practitioner who prescribes controlled substances, at each location where they do: + +1. Prepare their `User`, `Practitioner`, `PractitionerRole`, and `Location` as [Prescribing Controlled Substances](access-management/README.md#prescribing-controlled-substances) describes. +2. Add a DEA number to the `PractitionerRole`, as [DEA Qualification](access-management/access-change-requests.md#dea-qualification) describes. +3. The administrator creates a [prescribing nomination](access-management/access-change-requests.md#prescribing-nomination) for the practitioner. +4. An approver other than that administrator approves it through [second-person approval](access-management/access-change-requests.md#second-person-approval) before it [expires](access-management/access-change-requests.md#expiration). +5. Signed in as the practitioner, check that [`GET /e-prescription/access/epcs/permissions/mine`](access-management/list-permissions.md#list-your-own-permissions) returns `epcs-prescribing` at the location. + +## Verify the Setup + +Sign in as a practitioner who holds the permission, mark one of their controlled prescriptions ready to sign, and sign it. +If the module rejects a step: + +* `401`: the call had no acting user. Check [Call the Module as the Signed-In User](#call-the-module-as-the-signed-in-user). +* `403`: the call failed another check in [Prescribing Controlled Substances](access-management/README.md#prescribing-controlled-substances). diff --git a/docs/modules/eprescription/reference/environment-variables.md b/docs/modules/eprescription/reference/environment-variables.md index ce2c92374..f66cef703 100644 --- a/docs/modules/eprescription/reference/environment-variables.md +++ b/docs/modules/eprescription/reference/environment-variables.md @@ -21,6 +21,11 @@ Here is a full list of environment variables used by the module: +* `EPCS_MODE` – `full` enables controlled-substance prescribing, default is **disabled**. See [Enable EPCS](../epcs/enable-epcs.md). +* `EPCS_PROOF_SECRET` – Required when `EPCS_MODE` is `full`. Secret the module uses to detect a change to a controlled prescription between marking it ready to sign and signing it + + + * `QUEUE_DB_SERVER` - Queue database server address * `QUEUE_DB_PORT` - Queue database server port * `QUEUE_DB_NAME` - Queue database name From f014c1842dce6238c249fb34e4ff4fdbe2725622 Mon Sep 17 00:00:00 2001 From: GAlemsky Date: Fri, 20 Nov 2026 12:08:54 +0600 Subject: [PATCH 2/2] Improve EPCS enable docs --- .../modules/eprescription/epcs/enable-epcs.md | 34 +++++++++---------- .../reference/environment-variables.md | 4 +-- 2 files changed, 18 insertions(+), 20 deletions(-) diff --git a/docs/modules/eprescription/epcs/enable-epcs.md b/docs/modules/eprescription/epcs/enable-epcs.md index 55ab073c7..1f6c9b177 100644 --- a/docs/modules/eprescription/epcs/enable-epcs.md +++ b/docs/modules/eprescription/epcs/enable-epcs.md @@ -11,22 +11,19 @@ After this setup, a prescriber can mark a controlled prescription ready to sign 1. Set `EPCS_MODE` to `full`. With the default `disabled`, the module refuses controlled prescriptions. -2. Set `EPCS_PROOF_SECRET` to the output of `openssl rand -hex 32`, a random 64-character string. - The module uses it to detect a change to a controlled prescription between marking it ready to sign and signing it. - If you change the secret later, mark the prescriptions that are already ready to sign again before signing them. -3. Open `App/ePrescription-app` in the Aidbox console (`/ui/console#/entities/App`) and copy the value of `endpoint.secret`. - Aidbox authenticates every call it forwards to the module with this secret. - If it is empty or still `PUT_ENDPOINT_SECRET_HERE`, set it to the output of `openssl rand -hex 32` and save the App. -4. Set `AIDBOX_RPC_CREDENTIALS` to `base64("ePrescription-app:")`. - While it does not match `endpoint.secret`, the module answers every call from Aidbox with `401`, not only the EPCS calls. +2. Set `EPCS_PROOF_SECRET` to a random 64-character string (for example, the output of `openssl rand -hex 32`). + The module uses it to detect a change to a controlled prescription between marking it ready to sign and signing it. Changing the secret invalidates existing ready-to-sign proofs. +3. Open `App/ePrescription-app` in the Aidbox console (`/ui/console#/entities/App`) and check `endpoint.secret`. + If it is empty or still `PUT_ENDPOINT_SECRET_HERE`, set it to a separate random 64-character string (for example, the output of `openssl rand -hex 32`) and save the App. +4. Copy the current value of `endpoint.secret` and set `AIDBOX_RPC_CREDENTIALS` to the Base64 encoding of `ePrescription-app:`, substituting the copied value for ``. + The module uses this credential to authenticate every call from Aidbox. 5. Restart the module. -## Call the Module as the Signed-In User +## Configure User Authentication and Access Policies -1. Send each call that marks a prescription ready to sign, signs it, or manages EPCS access with the signed-in person's Aidbox authentication. - The module then gets an [acting user](access-management/configure-access-policies.md#acting-user) for the call. - A call made with only a `Client` credential has no acting user, and the module rejects it. -2. Write AccessPolicies that let your users call these operations: +1. Configure your EHR to use the signed-in user's Aidbox credentials for the operations listed below. + The module requires an [acting user](access-management/configure-access-policies.md#acting-user) for these operations. A `Client` credential alone does not identify one. +2. Write [AccessPolicies](../../../access-control/authorization/access-policies.md) that let your users call these operations: * `POST /e-prescription/rx/ready-to-sign`, which marks a prescription ready to sign * `POST /e-prescription/rx/new`, `POST /e-prescription/rx/respond-to-renewal`, and `POST /e-prescription/rx/respond-to-change`, which sign prescriptions * the EPCS access operations that [Configure Access Policies](access-management/configure-access-policies.md#access-policies) lists @@ -36,8 +33,9 @@ After this setup, a prescriber can mark a controlled prescription ready to sign Each location where practitioners prescribe controlled substances needs an administrator and an approver who are different users: 1. Appoint the administrator with [Bootstrap the First Administrator](access-management/bootstrap-the-first-administrator.md). -2. The administrator nominates the approver with an [access-change request](access-management/access-change-requests.md#request-a-change), and the nominee accepts it as the [first approver](access-management/access-change-requests.md#first-approver). -3. Check that [Location Compliance Status](access-management/location-compliance-status.md) returns `compliant: true` for the location. +2. Ask the administrator to nominate the approver with an [access-change request](access-management/access-change-requests.md#request-a-change). +3. Ask the nominee to accept the request as the [first approver](access-management/access-change-requests.md#first-approver). +4. Check that [Location Compliance Status](access-management/location-compliance-status.md) returns `compliant: true` for the location. ## Grant the Prescribing Permission @@ -45,8 +43,8 @@ For each practitioner who prescribes controlled substances, at each location whe 1. Prepare their `User`, `Practitioner`, `PractitionerRole`, and `Location` as [Prescribing Controlled Substances](access-management/README.md#prescribing-controlled-substances) describes. 2. Add a DEA number to the `PractitionerRole`, as [DEA Qualification](access-management/access-change-requests.md#dea-qualification) describes. -3. The administrator creates a [prescribing nomination](access-management/access-change-requests.md#prescribing-nomination) for the practitioner. -4. An approver other than that administrator approves it through [second-person approval](access-management/access-change-requests.md#second-person-approval) before it [expires](access-management/access-change-requests.md#expiration). +3. Ask the administrator to create a [prescribing nomination](access-management/access-change-requests.md#prescribing-nomination) for the practitioner. +4. Ask an approver other than the nominating administrator to give [second-person approval](access-management/access-change-requests.md#second-person-approval) before it [expires](access-management/access-change-requests.md#expiration). 5. Signed in as the practitioner, check that [`GET /e-prescription/access/epcs/permissions/mine`](access-management/list-permissions.md#list-your-own-permissions) returns `epcs-prescribing` at the location. ## Verify the Setup @@ -54,5 +52,5 @@ For each practitioner who prescribes controlled substances, at each location whe Sign in as a practitioner who holds the permission, mark one of their controlled prescriptions ready to sign, and sign it. If the module rejects a step: -* `401`: the call had no acting user. Check [Call the Module as the Signed-In User](#call-the-module-as-the-signed-in-user). +* `401`: check that the EHR uses the signed-in user's credentials. If every call from Aidbox returns `401`, check `AIDBOX_RPC_CREDENTIALS` in [Configure the Module](#configure-the-module). * `403`: the call failed another check in [Prescribing Controlled Substances](access-management/README.md#prescribing-controlled-substances). diff --git a/docs/modules/eprescription/reference/environment-variables.md b/docs/modules/eprescription/reference/environment-variables.md index f66cef703..6fd20fa68 100644 --- a/docs/modules/eprescription/reference/environment-variables.md +++ b/docs/modules/eprescription/reference/environment-variables.md @@ -21,8 +21,8 @@ Here is a full list of environment variables used by the module: -* `EPCS_MODE` – `full` enables controlled-substance prescribing, default is **disabled**. See [Enable EPCS](../epcs/enable-epcs.md). -* `EPCS_PROOF_SECRET` – Required when `EPCS_MODE` is `full`. Secret the module uses to detect a change to a controlled prescription between marking it ready to sign and signing it +* `EPCS_MODE` – Accepts `disabled` (default) or `full`. Set to `full` to enable controlled-substance prescribing. See [Enable EPCS](../epcs/enable-epcs.md). +* `EPCS_PROOF_SECRET` – Required when `EPCS_MODE` is `full`.