# kevincareycanvas/consent-capture

## Consent Capture

A Canvas plugin that lets clinical and front-desk staff **record a patient's** **consent right from the chart** — for _any number_ of consent types — and files a documented FHIR `Consent` for each: who collected it, when, from whom, by what method, plus a generated PDF (or, for written consents, the signed document itself).

The plugin surfaces consents three ways in the chart:

1. A **Consents** button in the chart header — **always present** for a patient. It is **red** when the patient still has a **required** consent that isn't on file, and a neutral **gray** button once all required consents are on file. Inactive/deceased patients always see the gray button and never the red one. (The label is always "Consents".)
2. A **Consents** launcher in the chart **app drawer** — always available, so staff can review what's on file or record an optional consent any time.
3. A **warning banner** on the chart and profile — shown while a required consent is outstanding, cleared once it's on file. Can be turned off entirely with the `CONSENT_BANNERS_ENABLED` plugin variable.

All three open (or reflect) the same **picker**, which lists every configured consent grouped into **Required**, **Optional**, and **On File**, and captures the selected one via the Canvas FHIR API.

The consents themselves are the **Patient Consent Codings** configured in Canvas admin — the plugin does not create them. What you configure at runtime, on the **Consent Settings** page (no code, no redeploy), is the _workflow_ layered onto each coding: the verbiage to read, the questions to ask, method/who/capacity, and whether it shows in the consent modal.

User & admin guides live in **[`docs/`](/content/docs/index.html)** (Markdown + printable PDFs): [Setup & Configuration](/content/docs/SETUP_GUIDE.md) for admins, and the [Staff Guide](/content/docs/RECORDING_GUIDE.md) / [Quick Start](/content/docs/RECORDING_QUICKSTART.md) for recording consents day to day.

* * *

## Why this plugin exists

Practices frequently capture **verbal, electronic, or written consents** (treatment, remote patient monitoring, care programs, etc.) during a visit and need a durable record of each. Doing this by hand is slow and error-prone, and it multiplies with every consent type a program requires.

Consent Capture turns that into a guided flow that:

- **Scales to many consents** — the picker lists every configured consent grouped by Required / Optional / On File, so staff see what's outstanding at a glance.
- **Chases the required ones** — the chart-header button turns red (and the chart/profile banner appears) only when a _required_ consent is missing, and both clear themselves when it's on file; the button then stays as a neutral gray entry point.
- **Records who did what** — the collecting staff member comes from the logged-in Canvas session, not from anything the browser sends.
- **Captures the details that matter** — the **method** (Verbal / Electronic / Written / Other), **who gave consent** (patient or a representative), per-consent **questions**, and a **capacity statement** — all configurable per consent.
- **Produces the right artifact** — a clean one-page PDF for verbal/electronic consents, or the provider-supplied **signed document** (camera-captured or uploaded) for written consents.
- **Files it as structured data** — a FHIR `Consent` (effective today, document attached) so the consent is queryable and shows in the record.
- **Is configured without code** — admins manage consents in Consent Settings.

* * *

## How it works (staff experience)

### Recording a consent

1. Open a patient chart. The **Consents** button in the chart header is always present; it turns **red** (with the warning banner) when an **active,** **non-deceased** patient has a required consent not on file, and is a neutral gray otherwise. The **Consents** app-drawer entry is always present.
2. Opening it shows the **picker**, grouped:
   - **Required** — required consents that are needed, or expired and due for **Renew**.
   - **Optional** — non-required consents that can be recorded.
   - **On File** — the patient's consent **history**: every accepted consent, shown **On file** (active) or **Expired**, including consents recorded outside this plugin or on codings it doesn't manage. Each row opens its attached document.
3. Selecting a consent starts the capture wizard: review the verbiage with the patient, then confirm:
   - **How is the consent being obtained?** — Verbal, Electronic, Written, or Other (limited to the methods the consent is configured for).
   - **Who is giving consent?** — the patient, or a representative (name + relationship, e.g. "Jane Doe (Daughter)").
   - A **capacity attestation** — when the consent requires one, a statement ("The patient/representative has the capacity/authority for decision-making.") is shown as a **Yes / No** affirmation (Yes pre-selected). Yes must stay selected to record; No blocks it. The wording follows the patient/representative choice and never inserts a name.
   - Any configured **questions** (Yes/No, Acknowledge, or typed answer). **Written** consents skip the questions — the signed document is the record — so none are shown or evaluated for them.
4. On **Record Consent**, the plugin:
   1. For verbal/electronic/other: generates a documentation PDF (built without an external PDF library, since the sandbox has none) with the method, capacity statement, questions, and full verbiage. For **Written**: the provider captures the signed document with the device camera (crop + multi-page, assembled into a PDF in the browser) or uploads a PDF — no PDF is generated.
   2. Creates a FHIR **Consent** (`status = active`, the consent's coding, effective date = the staff member's local calendar date, the document attached as `sourceAttachment`, **no** `period.end` — expiration is governed by the coding in Canvas admin).
   3. Reflects it under **On File** immediately.
> Canvas keeps **one consent per coding** and overwrites it on re-consent, so a coding shows a single current record; the On File section still lists distinct codings and any historical/unmanaged consents on file.

### The chart / profile banner

`ConsentBanner` keeps a red **"Required consent not on file."** warning banner in sync on the patient's **chart and profile**:

- Added when an **active, non-deceased** patient has a required consent not on file.
- Removed once all required consents are on file, or the patient becomes inactive or deceased.
- Recomputed on consent and patient events (`CONSENT_CREATED/UPDATED/DELETED`, `PATIENT_CREATED/UPDATED`).
- Suppressed entirely when the `CONSENT_BANNERS_ENABLED` variable is off — the handler then clears each banner as patients hit events (see below).

### Configuring consents (admin experience)

Open **Consent Settings** (the URL above, or the gear icon in the consent picker; access is limited — see below). The left list shows the consents you've configured, each with a status badge (Required / Optional / Not shown / Not set up). A **+** opens Canvas admin to add a new coding; a small flag icon links to the banner backfill page.

Pick a coding — the plugin only configures **pre-existing Patient Consent Codings**, never invents one — and configure its workflow:

| Field | Purpose |
| --- | --- |
| **General** (Name / Code / Expiration) | Read-only identity from the Canvas coding. | 
| **Show in the consent modal** | Whether providers can _record_ it in the picker. |
| **Prompt as due now** | Marks it required, so it lists under **Required** (and drives the button/banner) until on file. |
| **Position in the modal** | Order in the picker (editable, lower first). |
| **Content (verbiage)** | The consent language the provider reads. Blank lines start new paragraphs. |
| **Questions** | Asked and recorded in order (Yes/No, Acknowledge, Text; each required and optionally "must be Yes to record"). |
| **At capture** | Which methods are offered, whether to ask who is giving consent, and a capacity statement (templates use `[Patient name]` / `[Name]`). |

A live document preview shows how the PDF will read as you edit.

## Prerequisites

1. **Patient Consent Codings** in **Admin → Settings** — these _are_ the consents. The plugin lists them, layers workflow onto them, and checks them for status (and they're where expiration is set).
2. **Canvas FHIR API OAuth credentials** (client ID + secret) with permission to create `Consent` resources and read `Consent`/`Binary`. Stored as sensitive plugin variables, never in code.