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-16)
Last Updated: 2026-02-23
Overview
This guide covers configuration, permissions, and operational management for the Patient Statement Billing module.
Quick Reference
| I need to… | Pattern | Location |
|---|
| Configure billing permissions | Role-to-permission mapping for statement operations | Permission Configuration |
| Automate statement runs | Scheduled cron trigger to run-statement-cycle | Scheduling (Cron) |
| Run statements manually | Trigger on-demand statement cycle | Run Types |
Permission Configuration
Permission Keys
| Key | Category | Description |
|---|
pm.statements.view | view | View statement runs and delivery history |
pm.statements.generate | create | Trigger statement generation cycles |
pm.statements.manage | admin | Full management of statement runs |
pm.payment_plans.view | view | View payment plans |
pm.payment_plans.create | create | Create new payment plans |
pm.payment_plans.edit | edit | Modify existing payment plans |
pm.payment_plans.delete | delete | Delete payment plans |
pm.financial_assistance.view | view | View financial assistance applications |
pm.financial_assistance.create | create | Submit new applications |
pm.financial_assistance.review | approve | Review (approve/deny) applications |
Recommended Role Assignments
| Role | Permissions |
|---|
| Org Admin | All (auto-granted) |
| Billing Staff | statements.view/generate, payment_plans.*, financial_assistance.view/create |
| Collections | All billing + financial_assistance.review |
| Front Desk | statements.view, payment_plans.view, financial_assistance.view |
Statement Run Configuration
Run Types
- On Demand: Manually triggered by staff for immediate statement generation.
- Scheduled: Configured to run at specific intervals (requires cron setup).
- Cycle End: Triggered at the end of a billing cycle.
Scheduling (Cron)
Statement runs can be automated via the Supabase dashboard cron or pg_cron:
-- Example: Run monthly on the 1st at 6:00 AM UTC
SELECT cron.schedule(
'monthly-statements',
'0 6 1 * *',
$$SELECT net.http_post(
'https://<project-ref>.supabase.co/functions/v1/run-statement-cycle',
'{"organization_id": "<org-id>", "run_type": "scheduled"}'::jsonb,
'{}'::jsonb,
'{"Content-Type": "application/json"}'::jsonb
)$$
);
⚠️ Security: Do not embed secrets in cron payloads. The invoked function should retrieve privileged credentials from secure server-side secret storage (environment secrets/secret manager) at runtime.
Edge Function: run-statement-cycle
- Location:
supabase/functions/run-statement-cycle/index.ts
- Auth: Requires valid JWT with org access, or service role for cron invocations.
- Parameters:
organization_id (required), run_type, date_range_start, date_range_end, minimum_balance.
Delivery Channels
| Channel | Configuration Required |
|---|
| Print | None (generates PDF for download) |
| Email | Patient must have email on file; org email provider (Entra/Gmail) must be configured |
| Portal | Patient must have portal access (PM-12) |
| Text/SMS | SMS provider configured in CE module settings |
Database Tables
| Table | Purpose |
|---|
pm_statement_runs | Tracks statement generation cycles |
pm_statement_deliveries | Append-only delivery audit log |
pm_payment_plans | Patient payment plan agreements |
pm_financial_assistance_applications | Charity care / sliding scale applications |
RLS Policies
- SELECT/INSERT/UPDATE: Enforced via
pm_has_org_access(organization_id, auth.uid())
- DELETE: Restricted to
pf_is_org_admin(auth.uid(), organization_id)
- pm_statement_deliveries: Append-only — SELECT and INSERT only; no UPDATE or DELETE
Data Retention
- Statement deliveries are append-only and cannot be modified or deleted by any user role.
- Statement runs and their linked statements follow standard PM data retention policies.
Monitoring
Edge Function Logs
Monitor the run-statement-cycle function via:
Key Metrics
- Statements generated per run
- Delivery success/failure rates
- Average statement generation time
- Payment plan completion rates
- Financial assistance approval rates
Troubleshooting
| Issue | Resolution |
|---|
| Statement run fails | Check Edge Function logs for errors. Common causes: missing patient data, DB connection issues. |
| Email deliveries failing | Verify org email provider (Entra/Gmail) sender configuration and credentials. Check send-pending-notifications logs. |
| Permission denied errors | Verify user has correct role assignments in Organization Settings. |
| Statement amounts incorrect | Check pm_patient_statements data; verify charge capture (PM-07) is complete for the billing period. |
