> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Patient-Reported Outcomes & Self-Service Portal — Admin Guide

> This guide covers administrative configuration for the Patient-Reported Outcomes & Self-Service Portal feature. Organization administrators can manage permissi…

**Feature ID:** CL-26\
**Module:** CL (Clinical & EHR)\
**Version:** 1.0\
**Last Updated:** 2026-02-25

***

## Overview

This guide covers administrative configuration for the Patient-Reported Outcomes & Self-Service Portal feature. Organization administrators can manage permissions, review workflows, and understand the data model.

***

## Permission Configuration

CL-26 introduces three permission keys. These are automatically seeded for `org_admin` and `staff` roles.

| Permission Key                     | Description                                      | Recommended Roles                |
| ---------------------------------- | ------------------------------------------------ | -------------------------------- |
| `cl.patient-submissions.view`      | View submissions list and detail pages           | All clinical staff               |
| `cl.patient-submissions.review`    | Change submission status (reviewed/incorporated) | Licensed clinicians, supervisors |
| `cl.between-session-checkins.view` | View between-session check-in data               | All clinical staff               |

To modify role assignments:

1. Go to **Settings → Permissions** (org\_admin only).
2. Find the CL module permissions.
3. Assign or remove permissions per role as needed.

***

## Supported Screening Instruments

| Instrument      | Questions      | Scoring                                  | Crisis Detection           |
| --------------- | -------------- | ---------------------------------------- | -------------------------- |
| PHQ-9           | 9 (Likert 0–3) | 0–27, severity bands                     | Q9 (suicidal ideation) ≥ 1 |
| GAD-7           | 7 (Likert 0–3) | 0–21, severity bands                     | None                       |
| AUDIT-C         | 3 (Likert 0–4) | 0–12, positive ≥ 3                       | None                       |
| DAST-10         | 10 (Yes/No)    | 0–10, severity bands (Q3 reverse-scored) | None                       |
| C-SSRS Screener | 6 (Yes/No)     | 0–6 positive items                       | Any positive = crisis      |

***

## Data Model

### cl\_patient\_submissions

Stores all patient-submitted screening results.

| Column           | Type        | Description                                  |
| ---------------- | ----------- | -------------------------------------------- |
| id               | UUID        | Primary key                                  |
| organization\_id | UUID        | Tenant isolation                             |
| chart\_id        | UUID        | Patient chart (composite FK)                 |
| submission\_type | TEXT        | Instrument type (CHECK constraint)           |
| submitted\_at    | TIMESTAMPTZ | When patient submitted                       |
| responses        | JSONB       | Raw question responses                       |
| score\_result    | JSONB       | Auto-calculated score, severity, crisis flag |
| status           | TEXT        | pending\_review → reviewed → incorporated    |
| reviewed\_by     | UUID        | Clinician who reviewed                       |
| reviewed\_at     | TIMESTAMPTZ | When reviewed                                |
| custom\_fields   | JSONB       | Organization-specific metadata               |

### cl\_between\_session\_checkins

Append-only check-in records.

| Column                 | Type        | Description                       |
| ---------------------- | ----------- | --------------------------------- |
| id                     | UUID        | Primary key                       |
| organization\_id       | UUID        | Tenant isolation                  |
| chart\_id              | UUID        | Patient chart (composite FK)      |
| checkin\_at            | TIMESTAMPTZ | When patient checked in           |
| mood\_rating           | INTEGER     | 1–10 scale (CHECK constraint)     |
| medication\_adherence  | TEXT        | Adherence level                   |
| crisis\_flag           | BOOLEAN     | Patient-reported crisis indicator |
| crisis\_warning\_signs | TEXT        | Free-text warning signs           |
| custom\_fields         | JSONB       | Organization-specific metadata    |

***

## RLS & Security

* **Row Level Security** is enabled and forced on both tables.
* **Portal patients** can only see/insert data for their own charts (via `cl_portal_chart_ids_for_user` SECURITY DEFINER helper).
* **Clinicians** access data scoped to their organization via `cl_has_org_access`.
* **UPDATE policies** include `WITH CHECK` to prevent cross-tenant data movement.
* Check-ins are **append-only** — no UPDATE or DELETE policies exist.

***

## Crisis Escalation Flow

When a submission triggers crisis detection:

1. **Patient sees:** Crisis resources banner (988, Crisis Text Line, SAMHSA) immediately after submission.
2. **In-Basket:** An **urgent** priority in-basket item is created in CL-23 for the care team.
3. **Clinician action:** Clinician reviews the submission and takes appropriate clinical action.

Crisis triggers:

* PHQ-9: Question 9 (suicidal ideation) score ≥ 1
* C-SSRS: Any positive item
* Check-in: Crisis flag toggled by patient

***

## Integration Points

| System                | Integration                           | Direction     |
| --------------------- | ------------------------------------- | ------------- |
| CL-23 In-Basket       | In-basket items created on submission | CL-26 → CL-23 |
| PM-12 Portal          | Patient identity and chart scoping    | PM-12 → CL-26 |
| CL-03 Treatment Plans | Read-only portal view                 | CL-03 → CL-26 |
| PF-10 Notifications   | Crisis escalation alerts              | CL-26 → PF-10 |

***

## Troubleshooting

**Q: Portal patients can't see the screening page.**\
A: Ensure the patient has an active `pm_portal_users` record with a linked `portal_patient_id` in `pf_profiles`. The RLS helper `cl_portal_chart_ids_for_user` must return chart IDs for the patient.

**Q: Submissions aren't appearing in the clinician list.**\
A: Check that the clinician has `cl.patient-submissions.view` permission and belongs to the same organization as the submission.

**Q: Crisis in-basket items aren't being created.**\
A: Verify CL-23 tables exist and the `usePatientSubmissionInbasket` hook is invoked after submission creation.