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

# Practice Management Group Sessions

> Define and manage group therapy session templates; view group definitions with sessions, enrollments, and capacity management.

This page manages group session definitions — the reusable templates for recurring group therapy and psychoeducation sessions — and is reached at `/pm/groups`.

## Overview

The Group Sessions page lists group definition records from `pm_group_definitions`, filtered to active groups (`is_active = true`) by default. Definitions are joined with the facilitator's `pf_profiles` record to show the facilitator name. Each card displays the **group name**, **group type** badge, **facilitator**, **maximum capacity**, and **session duration** in minutes, plus an Active/Inactive status badge and a **View** button. The page includes a debounced search field (300 ms) and a **Type** dropdown for filtering. Staff with `PM_PERMISSIONS.GROUP_DEFINITIONS_CREATE` see a **New Group** button that opens the `GroupDefinitionFormDialog`; on creation, navigation goes directly to the new group's detail page.

## Who it's for

Requires permission: `PM_PERMISSIONS.GROUP_DEFINITIONS_VIEW` (`pm.group_definitions.view`).

Creating new group definitions additionally requires `PM_PERMISSIONS.GROUP_DEFINITIONS_CREATE`.

## Before you start

* You must hold the `pm.group_definitions.view` permission.
* A facilitator (staff member with a `pf_profiles` record) must exist before it can be assigned to a group.

## Steps

<Steps>
  <Step title="Open Group Sessions">
    Navigate to **Practice Management → Groups** or go directly to `/pm/groups`. Active group definitions load ordered alphabetically by `group_name`.
  </Step>

  <Step title="Search and filter">
    Type in the **Search groups…** field to filter by group name (debounced 300 ms). Use the **Type** dropdown to filter by group type: Therapy, Psychoeducation, Skills Training, Support, IOP, PHP, or Other.
  </Step>

  <Step title="View a group definition">
    Click **View** on any card to navigate to `/pm/groups/:id` for the full definition detail, scheduling, and enrollment information.
  </Step>

  <Step title="Create a new group definition (if permitted)">
    Click **New Group** in the page header to open the `GroupDefinitionFormDialog`. Complete the form and submit. On success you are navigated directly to the new group's detail page.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Group types">
    Seven types are defined: **therapy**, **psychoeducation**, **skills\_training**, **support**, **iop** (Intensive Outpatient Program), **php** (Partial Hospitalization Program), and **other**.
  </Accordion>

  <Accordion title="Active / Inactive groups">
    The list page shows only active groups by default (`is_active: true`). Inactive groups are not displayed unless the filter is changed.
  </Accordion>

  <Accordion title="Empty state">
    When no groups match the current search or type filter, the page shows "No groups match your criteria. Try adjusting filters." When no groups exist at all, it shows "Create your first group session definition to get started."
  </Accordion>

  <Accordion title="Error state">
    If the query fails, an inline card displays the sanitized error message.
  </Accordion>
</AccordionGroup>

## Viewing a group

The Group Details screen displays a single group definition with its scheduled sessions and enrolled patients at route `/pm/groups/:id` (permission: `pm.group_definitions.view`).

The page loads a group definition via `useGroupDefinitionDetail`, schedule occurrences via `useGroupScheduleList`, and enrollments via `useGroupEnrollmentsList`. The header shows group name with an edit button (requires `PM_PERMISSIONS.GROUP_DEFINITIONS_EDIT`), group type badge (therapy, psychoeducation, skills training, support, IOP, PHP, other), active/inactive badge, facilitator name, location name, and enrolled count vs. max capacity. Two tabs organize the content: **Schedule** and **Enrollments**.

On the Schedule tab, each session card shows date, start–end time, and a status badge; scheduled sessions can be cancelled via the cancel button (requires `PM_PERMISSIONS.GROUP_SCHEDULE_EDIT`). The Add Session button (requires `PM_PERMISSIONS.GROUP_SCHEDULE_CREATE`) opens `GroupScheduleOccurrenceFormDialog`.

On the Enrollments tab, each patient card shows patient name, MRN, enrollment status, and optional waitlist position; enrolled/waitlisted patients can be disenrolled (requires `PM_PERMISSIONS.GROUP_ENROLLMENTS_EDIT`). The Enroll Patient button (requires `PM_PERMISSIONS.GROUP_ENROLLMENTS_CREATE`) opens `GroupEnrollmentFormDialog`.

1. From the Group Sessions list (`/pm/groups`), click a row to open the group detail page.
2. The header shows group type, active status, facilitator, location, and current enrollment count vs. max capacity.
3. On the **Schedule** tab: view existing sessions with date, time, and status. Add a new session with **Add Session** (requires `pm.group_schedule.create`) or cancel a scheduled session (requires `pm.group_schedule.edit`).
4. On the **Enrollments** tab: view enrolled patients with status and waitlist position. Enroll a patient with **Enroll Patient** (requires `pm.group_enrollments.create`) or disenroll (requires `pm.group_enrollments.edit`).

| Term                  | Meaning in code                                                                   |
| --------------------- | --------------------------------------------------------------------------------- |
| `group_type`          | `therapy`, `psychoeducation`, `skills_training`, `support`, `iop`, `php`, `other` |
| `max_capacity`        | Maximum number of enrolled patients allowed                                       |
| `enrollment_status`   | `enrolled`, `waitlisted`, `disenrolled`, `completed`                              |
| `waitlist_position`   | Numeric position in the waitlist if status is `waitlisted`                        |
| `GroupScheduleStatus` | `scheduled`, `in_progress`, `completed`, `cancelled`                              |
| `facilitator_id`      | Linked provider/facilitator for the group                                         |

## Related

<Columns cols={2}>
  <Card title="Practice Management" icon="briefcase" href="/pm/overview">
    Overview of the Practice Management core.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/pm.tsx
  * src/cores/pm/pages/GroupDefinitionsListPage.tsx
  * src/cores/pm/hooks/useGroupDefinitionsList.ts
  * src/cores/pm/types/groups.ts
  * src/cores/pm/pages/GroupDefinitionDetailPage.tsx
  * src/cores/pm/hooks/useGroupDefinitionDetail.ts
  * src/cores/pm/hooks/useGroupScheduleList.ts
  * src/cores/pm/hooks/useGroupEnrollmentsList.ts
</Accordion>