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

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. 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

---

​

Data Model

​

cl_patient_submissions

Stores all patient-submitted screening results.

​

cl_between_session_checkins

Append-only check-in records.

---

​

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

---

​

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.