Watchlists & Change Monitoring
Subscribe to utilities and receive alerts when interconnection procedures change.
What are Watchlists?
A watchlist is your set of tracked utilities. When you watch a utility, GridWonk continuously monitors its interconnection requirements for changes and notifies you when something differs from the last known state. This keeps your team informed without manual checking.
Watching and Unwatching a Utility
In the Utility Selector dialog, each utility row displays a Watch button with a star icon.
| Action | How |
|---|---|
| Watch | Click the star button on any utility row. The button turns amber and reads "Watching". |
| Unwatch | Click the amber "Watching" button again to stop tracking that utility. |
If a state filter is active, the subscription is scoped to that specific state. For single-state utilities, the state is set automatically. Multi-state utilities with no filter are watched at the utility level across all states.
The star is the only place to subscribe. The console header used to carry its own watch control; it was removed because a subscription belongs to a utility rather than to whichever project you happen to have open. To review what you are watching, use Manage Watched Utilities in the Utility Selector header, which opens the Requirements Change Monitoring card on your dashboard.
What Changes are Detected
The monitoring pipeline computes a fingerprint of each watched utility's technically published Packet Intake requirements and compares it to the previous scan. It does not read the frozen legacy requirement table. A state still scopes the subscription and notification; the published requirement catalog itself is currently keyed to the exact utility rather than a separate state row. Detected change types include:
| Change Type | Description |
|---|---|
| Requirements Updated | Requirement text, count, or content hash changed |
| Document Added | A new procedure document appeared for the utility |
| Document Removed | A previously tracked document is no longer found |
| Validation Rule Updated | A form-validation or cross-document rule changed |
Each change event records a title, summary, severity, and metadata about what shifted.
The first scan of a newly watched utility records a monitoring baseline instead of an alert: there is no previous scan to compare against, so the event is logged and no notification is sent. The move to Packet Intake requirements did the same thing once per already-watched utility. Alerts resume with the next real change.
Severity Levels
Severity is assigned automatically based on how much the requirement set changed:
| Severity | Criteria |
|---|---|
| Low | Fingerprint changed but requirement count stayed the same (text-only edits), or the event is a monitoring baseline |
| Medium | Requirement count changed |
| High | Requirement count changed by 20% or more compared to the previous scan |
High-severity changes indicate substantial procedure revisions that may affect active applications.
Detection Frequency
GridWonk runs a single automated pipeline every 30 minutes:
| Pipeline | Frequency | Purpose |
|---|---|---|
| Detect Requirement Changes | Every 30 minutes | Scans watched utilities for fingerprint changes, then delivers pending email notifications |
Both detection and notification delivery happen in the same cron handler. Up to 200 scopes are checked per detection run and up to 50 notifications are processed per delivery run.
How Notifications Work
When a change is detected, a notification row is queued for each user subscribed to that utility and state. The notification pipeline then:
- Looks up the user's email address
- Sends a change alert email with the utility name, state, summary of what changed, and a link to the dashboard
- Updates the subscription's
lastNotifiedAttimestamp
If delivery fails, GridWonk stores a redacted failure reason for diagnosis and raises an operational alert grouped by failure type. The cron fallback gets a fresh three-alert budget for each sweep. Queue deliveries do not share that budget, so a warm server instance cannot permanently silence later failures; the alert service's 15-minute, failure-class throttle controls repetition across requests.
The operational alert identifies the affected account when it is stored with the subscription, and the user as the notification recipient. It does not attribute a system delivery failure to that user.
Non-email notification methods (e.g., in-app events) are marked as delivered immediately for future expansion.
Viewing Change History
Recent change events are available through the Recent Changes list, which can be filtered by:
- Utility — Show events for a specific utility
- State — Narrow to a two-letter state code
- Search query — Free-text search across event titles and summaries
Events are sorted newest-first and display the severity, title, summary, and detection timestamp.
Where Change Signals Surface
Watchlist subscriptions drive both the change event data and the notification delivery for high-severity procedure updates. The console's aggregate Analytics destination that used to summarize those signals has been retired; the Portfolio view covers project status, and the change events themselves reach you through notifications.
Who Can Use Watchlists
Watchlists are available in developer organization contexts. Each subscription is scoped to the user and organization, so team members manage their own watch preferences independently.
Creating or deleting a subscription is a write operation. Direct users need an active Member, Admin, or Owner role. Grant-derived access also requires a write or admin grant and a Member-or-higher role in the receiving organization. Viewer and read-grant access can inspect allowed data but cannot change watch preferences.