Document alert tickets

README, INTEGRATIONS (the osTicket ticket API: fields, making the key, what is sent, what it can't do,
what wasn't verified), NOTIFICATIONS (the rules, in one table), ROLES, DATABASE (the new table, the
settings key, the internal flags, what deleting an integration does), and the Privacy page (the one new
thing that leaves the app: an alert's text, to your osTicket).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-07 23:41:47 +02:00
1 parent 96c93ef924
commit aec553f122
5 files changed
+86 -8

No files matched your search

+28 -4
View File
@@ -101,16 +101,40 @@ in three ways:
failing its last few calls (before the threshold that triggers an "integration down" notification).
It runs the checks live when opened (a recent result is reused for a minute), and shows what it couldn't read at the top, so a missing section means
"couldn't check" and not "all clear".
"couldn't check" and not "all clear". An alert that has an osTicket ticket (see the next section) shows its ticket number.
## Tickets in osTicket
Not a notification, but it acts on the same alerts: with **Settings → Alert tickets** switched on (off by default), a problem on the Alerts page opens a
ticket in osTicket. It runs every 15 minutes, starting about a minute and a half after the app starts.
| Rule | What it means |
|---|---|
| Which problems | The severities and kinds you choose — **critical and warning, every kind** by default. Info (updates waiting and the like) is off. |
| Must last | A problem must be there in **2 checks in a row** (15–30 minutes) before it opens a ticket, so a blip that fixes itself — one failed call to an integration, a monitor that flickers — never does. Can be set from 1 (at once) to 4. |
| One ticket per problem | However many checks see it, once. After a ticket is open, the problem isn't ticketed again while it lasts — even if someone closes the ticket in osTicket. |
| Comes back | A problem that clears and returns **within 60 minutes** is the same problem (no new ticket). After longer, it is a new one and gets a new ticket. |
| Many at once | **More than 5 new problems in one check** become a single summary ticket listing them all, so one outage doesn't fill the queue. Up to 5 get a ticket each. |
| Maintenance windows | A problem under one never opens a ticket. If it is still there after the window ends, it does. |
| Never about osTicket | Overdue tickets, and osTicket's own calls failing, never open a ticket — it would go to the thing that is down, or add to the pile. |
| Already there at switch-on | **Left alone by default**: the first check after switching on records what is wrong as the starting line, and only problems that start after it get a ticket. Can be set to ticket those too. Switching it off and on again starts a new line. |
| If osTicket can't be reached | Nothing is recorded as opened; the next check tries again. A refused key, a wrong address and similar are shown on the settings page and in the Diagnostic Log. |
| If something can't be read | When a check couldn't read everything (an integration was down), nothing is treated as gone, so a problem isn't called cleared just because its source couldn't be looked at. |
The ticket says what is wrong, the severity, the kind, where it comes from, when it was first seen, and links back to the problem in this app. osTicket's
API can't update or close a ticket, so it isn't touched again: close it in osTicket when the problem is dealt with. Every ticket opened (and every test
ticket) is in the Audit Log as `alert_ticket`, and changes to the settings as `settings` / `update_alert_tickets`. "Send a test ticket" and "Check now"
on the settings page use the saved settings.
## What does *not* send a notification
Worth calling out explicitly, since it's easy to assume everything in
the app alerts on something:
- **osTicket** — the integration lists open tickets, but there is no
scheduled check or alert wired up for it (e.g. nothing pings you about
a newly-overdue ticket). It's a read-only dashboard/page today.
- **osTicket's own tickets** — the integration lists open tickets, but
there is no notification for it (e.g. nothing pings you about a
newly-overdue ticket); the page and the Alerts page show them. (The
other direction — an alert opening a ticket — is the section above.)
- **phpIPAM sync**, **Uptime Kuma monitor/maintenance import**, and any
other manual "Sync from X" action — these run when you click the
button and report their result on the page itself, not via a