Overview
Billing
Subscription ManagementBackground Jobs
SanctuaryOS runs a set of automated background jobs that keep your data current, generate alerts, and handle recurring tasks without manual intervention. These jobs are managed by the Tenant Scheduler, which dispatches work every hour based on each tenant's local timezone.
Getting Here
Navigation: Settings → System → Background Jobs
The Background Jobs settings page shows all scheduled tasks, their last run status, and allows you to manually trigger any job with the “Run Now” button.
How Scheduling Works
The master scheduler runs every hour on the hour. For each active tenant, it checks the tenant's local timezone (derived from the tenant or primary campus configuration, defaulting to America/Toronto) and dispatches the appropriate jobs based on the local hour and day of the week.
Every job execution is tracked in the JobRunLog table with a status of RUNNING, SUCCESS, or FAILED, along with duration and any error messages. This makes it easy to audit job history and diagnose failures.
Job Schedule Reference
Nightly Window (2am–5am local)
| Field | Type | Description |
|---|---|---|
| Serve Stats Recalculation | Daily, 2am | Recomputes serve counts (90-day, YTD, all-time), confirmation rates, and estimated hours for every active team member. |
| Care Milestone Scan | Daily, 2am | Scans all members for upcoming birthdays, wedding anniversaries, baptism anniversaries, membership anniversaries, and salvation anniversaries within the configured lead-day window (default 30 days). |
| Care Snooze Wakeup | Daily, 3am | Reactivates snoozed care items whose snooze period has expired. |
| Bereavement Anniversaries | Daily, 3am | Creates care milestones for bereavement anniversary dates approaching within the lead-day window. |
Morning Window (6am–8am local)
| Field | Type | Description |
|---|---|---|
| Service Materialisation | Monday, 6am | Creates upcoming service instances from active service patterns for the next several weeks. Ensures your calendar always has services ready. |
| Monthly Statements | 1st of month, 6am | Auto-generates giving statements for the previous month (if enabled in tenant configuration). Can optionally auto-email statements to donors. |
| Absence Alert Scan | Monday, 7am | Scans attendance records to identify members who have missed a configurable number of consecutive services (default: 2). Creates, updates, or resolves absence alerts. |
| Care Follow-Up Reminders | Daily, 7am | Sends reminder notifications for care items with upcoming or overdue follow-up dates. |
| Circles Join Digest | Monday, 8am | Sends a weekly digest email to group leaders summarizing pending join requests. |
Weekly Jobs (Monday)
| Field | Type | Description |
|---|---|---|
| Burnout Scan | Monday, 1am | Identifies volunteers whose serve count in the last 90 days exceeds the team average by the configured threshold multiplier (default: 2x). Sends burnout alerts to team leaders. |
Queue-Based Jobs (On Demand)
| Field | Type | Description |
|---|---|---|
| Statement Generation | On demand | Processes statement runs via BullMQ. Triggered when a user creates a statement run from the Steward module. |
| ZIP Generation | On demand | Packages generated statement PDFs into downloadable ZIP files. Runs with concurrency of 3. |
| ZIP Cleanup | Every 30 minutes | Deletes expired ZIP files from storage to free disk space. |
| Circles Health Score | On demand | Recalculates health scores for small groups. Triggered after attendance is logged, or can be run as a batch for all groups. |
Subscription and Platform Jobs
| Field | Type | Description |
|---|---|---|
| Trial Reminders | Daily, 9am | Sends email reminders to churches at 15, 8, 3, and 1 days before trial expiration. |
| Trial Expiration Check | Daily, 10am | Notifies churches whose trial period has ended. |
| Dunning | Daily, 11am | Sends payment reminder emails to past-due accounts. Auto-suspends accounts past due for over 30 days. |
| Data Retention | Daily, 3am | Sends data retention warnings to cancelled tenants at 30, 7, and 1 days before the 1-year purge deadline. Deactivates tenants cancelled over 1 year ago. |
| Signup Cleanup | Hourly (:30) | Expires stale pending signups that have been in INITIATED or EMAIL_VERIFIED status for over 24 hours. |
| Onboarding Sequence | Daily, 11am | Sends timed onboarding emails: welcome (day 0), import members (day 2), configure giving (day 5), setup services (day 8), invite team (day 12). |
| Escalation Check | Every 6 hours | Finds volunteer confirmation requests that have timed out (default 48 hours) and auto-assigns the slot to the next available candidate. |
| Re-confirmation | Daily, 10am | Sends "Still coming?" emails to confirmed volunteers whose service is within the next 24-48 hours. |
Running Jobs Manually
From the Background Jobs settings page, click the Run Now button next to any job to trigger it immediately. The page will refresh after a few seconds to show the updated status. Manual runs are logged the same way as scheduled runs.
This is useful for testing, recovering from a missed schedule, or forcing a refresh after importing data.
Monitoring Job Health
Each job card on the settings page shows:
- Status indicator — green (last run succeeded), red (last run failed), blue (currently running), gray (never run)
- Schedule — the cron expression in human-readable form
- Last run — relative timestamp (e.g., “2h ago”)
- Duration — how long the last run took in milliseconds
- Error details — hover over the warning icon to see the error message for failed jobs