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/ (Markdown + printable PDFs): Setup & Configuration for admins, and the Staff Guide / Quick Start 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:

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.