Encore OS — Documentation

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:

Supabase Edge Function Logs

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.

Patient Statement Billing — User Guide Multi-Site Billing Configuration — Admin Guide

Guides

Patient Registration & Portal

Scheduling & Resources

Eligibility & Authorizations

Claims & Clearinghouse

Revenue Cycle & Charges

Payments & Statements

Contracts & Value-Based Care

Estimates & Financial Counseling

Payers & Provider Enrollment

Compliance & Audit

Patient Statement Billing — Admin Guide

Overview

Quick Reference

Permission Configuration

Permission Keys

Recommended Role Assignments

Statement Run Configuration

Run Types

Scheduling (Cron)

Edge Function: `run-statement-cycle`

Delivery Channels

Database Tables

RLS Policies

Data Retention

Monitoring

Edge Function Logs

Key Metrics

Troubleshooting

​Overview

​Quick Reference

​Permission Configuration

​Permission Keys

​Recommended Role Assignments

​Statement Run Configuration

​Run Types

​Scheduling (Cron)

​Edge Function: run-statement-cycle

​Delivery Channels

​Database Tables

​RLS Policies

​Data Retention

​Monitoring

​Edge Function Logs

​Key Metrics

​Troubleshooting

​Related

Overview

Quick Reference

Permission Configuration

Permission Keys

Recommended Role Assignments

Statement Run Configuration

Run Types

Scheduling (Cron)

Edge Function: `run-statement-cycle`

Delivery Channels

Database Tables

RLS Policies

Data Retention

Monitoring

Edge Function Logs

Key Metrics

Troubleshooting

Related