Skip to main content

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.

Module: Practice Management (PM)
Feature: PM-04 Group Session Scheduling
Version: 1.0
Updated: 2026-02-19

​
Overview

This guide covers permission configuration, role assignments, capacity management, waitlist behavior, and data administration for the Group Session Scheduling feature (PM-04).

​
Permission Key Reference

Permission KeyConstantDescription
pm.group_definitions.viewPM_PERMISSIONS.GROUP_DEFINITIONS_VIEWView group definition list and detail pages
pm.group_definitions.createPM_PERMISSIONS.GROUP_DEFINITIONS_CREATECreate new group definitions
pm.group_definitions.editPM_PERMISSIONS.GROUP_DEFINITIONS_EDITEdit existing group definitions
pm.group_definitions.deletePM_PERMISSIONS.GROUP_DEFINITIONS_DELETESoft-delete group definitions
pm.group_schedule.viewPM_PERMISSIONS.GROUP_SCHEDULE_VIEWView schedule occurrences
pm.group_schedule.createPM_PERMISSIONS.GROUP_SCHEDULE_CREATECreate new session occurrences
pm.group_schedule.editPM_PERMISSIONS.GROUP_SCHEDULE_EDITEdit session occurrences
pm.group_schedule.deletePM_PERMISSIONS.GROUP_SCHEDULE_DELETECancel session occurrences
pm.group_enrollments.viewPM_PERMISSIONS.GROUP_ENROLLMENTS_VIEWView enrollment list and waitlist
pm.group_enrollments.createPM_PERMISSIONS.GROUP_ENROLLMENTS_CREATEEnroll patients into groups
pm.group_enrollments.editPM_PERMISSIONS.GROUP_ENROLLMENTS_EDITUpdate enrollment status (disenroll, promote)
pm.group_enrollments.deletePM_PERMISSIONS.GROUP_ENROLLMENTS_DELETERemove enrollment records

​
Default Role Assignments

These assignments are seeded by the PM-04 database migration (pf_role_permissions):
System RoleDefinitions (V/C/E/D)Schedule (V/C/E/D)Enrollments (V/C/E/D)
org_admin✅ ✅ ✅ ✅✅ ✅ ✅ ✅✅ ✅ ✅ ✅
staff✅ — — —✅ — — —✅ — — —
Note: The org_admin role automatically receives all active permissions via the platform trigger. Custom roles can be configured in Settings > Permissions.

​
Managing PM-04 Permissions

  1. Navigate to Settings > Permissions (requires org_admin role).
  2. Select the Practice Management module from the module list.
  3. Locate the Group Definitions, Group Schedule, and Group Enrollments permission groups.
  4. Assign or revoke permissions per role using the toggle interface.
  5. Changes take effect immediately for newly issued tokens; existing sessions refresh on next page load.

​
Capacity and Waitlist Configuration

​
Capacity Fields

FieldTableDescription
max_capacitypm_group_definitionsMaximum number of enrolled patients. Required.
min_capacitypm_group_definitionsMinimum patients to hold a session. Optional.

​
Automatic Capacity Enforcement

When a patient is enrolled via the UI or API:
  1. The system counts current enrollments with status = 'enrolled' for that group.
  2. If the count is below max_capacity, the patient is enrolled with status = 'enrolled'.
  3. If the count equals or exceeds max_capacity, the patient is automatically placed on the waitlist with status = 'waitlisted' and assigned the next waitlist_position.

​
Waitlist Auto-Promotion

When an enrolled patient is disenrolled (status changed to disenrolled):
  1. The system queries the waitlist for that group, ordered by waitlist_position ASC.
  2. The patient with the lowest waitlist_position is automatically promoted to status = 'enrolled'.
  3. Their waitlist_position is cleared (NULL).
  4. A toast notification informs the user of the promotion.

​
Manual Override

Administrators can override capacity by directly editing the max_capacity field on the group definition. Reducing capacity below current enrollment does not automatically disenroll patients — the group will display as over-capacity until resolved manually.

​
Soft Delete and Data Retention

Group definitions and enrollments use soft deletion — the deleted_at column is set to the current timestamp, and records are hidden from standard views. Soft delete behavior:
  • Records remain in the database for audit and recovery.
  • Application queries filter deleted_at IS NULL.
  • RLS policies enforce this at the database level.
  • Schedule occurrences linked to deleted groups are not affected.
To restore a soft-deleted group definition: 
UPDATE pm_group_definitions
SET deleted_at = NULL, updated_at = NOW()
WHERE id = '<group_id>'
  AND organization_id = '<your_org_id>';
To restore a soft-deleted enrollment: 
UPDATE pm_group_enrollments
SET deleted_at = NULL, updated_at = NOW()
WHERE id = '<enrollment_id>'
  AND organization_id = '<your_org_id>';
Permanent deletion is not available through the UI and should only be performed by a database administrator in compliance with your organization’s data retention policy.

​
Database Tables

TableDescription
pm_group_definitionsGroup metadata: name, type, facilitator, capacity, recurrence
pm_group_scheduleIndividual session occurrences with date, time, status
pm_group_enrollmentsPatient enrollment records with status and waitlist position
All tables have RLS enabled with FORCE ROW LEVEL SECURITY. The pm_has_org_access SECURITY DEFINER helper function prevents RLS recursion by checking organization_id membership.

​
Key Columns

pm_group_definitions:
  • organization_id — Tenant isolation (required)
  • group_type — CHECK constraint: therapy, psychoeducation, skills_training, support, iop, php, other
  • facilitator_id, co_facilitator_id — References to staff profiles
  • max_capacity, min_capacity — Enrollment limits
  • deleted_at — Soft delete timestamp
  • custom_fields — JSONB for org-specific extensions
pm_group_schedule:
  • group_definition_id — FK to pm_group_definitions
  • session_date, start_time, end_time — Session timing
  • status — scheduled, completed, cancelled
  • cancellation_reason — Required when status is cancelled
pm_group_enrollments:
  • group_definition_id — FK to pm_group_definitions
  • patient_id — FK to pm_patients
  • status — enrolled, waitlisted, disenrolled
  • waitlist_position — Integer position when waitlisted
  • deleted_at — Soft delete timestamp

​
Domain Events

EventTriggerPayload
pm_group_session_scheduledSession occurrence created{ group_id, session_id, session_date }
pm_group_session_cancelledSession occurrence cancelled{ group_id, session_id, reason }
These events are available for downstream consumers (e.g., CL-14 clinical documentation) via the Platform Integration Layer.