Circles Health
Billing
Subscription ManagementCircles Health Score
CirclesThe Circles Health Score job computes a composite health rating for each active small group based on attendance, meeting consistency, and group size. The score is used to surface struggling groups on the Circles dashboard and help leaders identify groups that need attention.
Schedule
When: On demand (triggered after attendance is logged) and available as a batch operation for all groups.
Unlike most background jobs, the health score is primarily computed on demand — each time a meeting log is recorded for a group, the score is recalculated for that specific group. A batch processor is also available to recompute scores for all active groups across all tenants.
How It Works
The health score algorithm evaluates three dimensions and produces a weighted composite score from 0 to 100:
Scoring Dimensions
| Field | Type | Description |
|---|---|---|
| Attendance Score | 45% weight | Average attendance rate across the last 8 completed meetings. Calculated as total present / (total present + total absent). Defaults to 50 if no completed meetings exist. |
| Consistency Score | 35% weight | Ratio of completed meetings to total meeting slots in the last 8 entries. A group that holds all scheduled meetings scores 100; one that cancels frequently scores lower. |
| Size Score | 20% weight | Penalizes groups that are too small (under 4 members: score 30) or over capacity (score 40). Groups with 6-15 members score a perfect 100. Default for other sizes is 70. |
Composite Calculation
The overall score is: (Attendance x 0.45) + (Consistency x 0.35) + (Size x 0.20), rounded to the nearest integer.
What Gets Stored
| Field | Type | Description |
|---|---|---|
| Overall Score | 0-100 | The composite health score, stored in the CircleGroupHealthScore table with dimension = OVERALL. |
| Previous Score | 0-100 | The previous OVERALL score, used to calculate trend direction (improving, declining, stable). |
| Period | Date range | The 90-day window used for calculation (periodStart to periodEnd). |
| Factors | JSON | Detailed breakdown: attendance score, consistency score, size score, member count, and meetings held. |
| Denormalized Score | Integer | The healthScore field on the CircleGroup record is updated directly for fast querying and dashboard display. |
Included Groups
The batch processor scores all groups that are not in CLOSED, MERGED, or ARCHIVED status. This means active, paused, and forming groups all receive health scores.
Interpreting Scores
- 80–100: Healthy — group is meeting consistently with good attendance and appropriate size
- 60–79: Moderate — some areas could improve (e.g., inconsistent meetings or declining attendance)
- 40–59: Needs attention — consider reaching out to the group leader
- Below 40: At risk — the group may need restructuring, leadership support, or to be merged with another group
Job Output
The batch run reports:
- Processed — number of groups that received a new health score
- Failed — number of groups where score computation encountered an error