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:
1 parent
96c93ef924
commit
aec553f122
5 files changed
+86
-8
No files matched your search
+25
-2
@@ -24,7 +24,7 @@ what the app actually creates.
|
||||
| **File** | `DATABASE_PATH`, default `../data/homelab-manager.sqlite` (relative to `server/`; `/app/data/...` in Docker). The folder is created if missing. |
|
||||
| **Foreign keys** | Switched on for every connection (`PRAGMA foreign_keys = ON`), so the `ON DELETE` rules below are enforced. |
|
||||
| **Migrations** | SQL files in [`server/drizzle/`](server/drizzle) (`0000` … `0014`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. |
|
||||
| **Tables** | 21 application tables, plus drizzle's own `__drizzle_migrations`. |
|
||||
| **Tables** | 22 application tables, plus drizzle's own `__drizzle_migrations`. |
|
||||
|
||||
**Not in the database:**
|
||||
|
||||
@@ -58,6 +58,7 @@ erDiagram
|
||||
servers ||--o{ server_ports : "cascade"
|
||||
servers ||--o{ port_forwards : "optional (set null)"
|
||||
integrations ||--o{ servers : "proxmox link (app clears it)"
|
||||
integrations ||--o{ alert_tickets : "osTicket used (set null)"
|
||||
```
|
||||
|
||||
Eight tables stand alone, with no foreign keys: `settings`, `secrets`,
|
||||
@@ -95,7 +96,7 @@ Who changed what. Written by the app on every change (see
|
||||
| `id` | integer PK | |
|
||||
| `actor_user_id` | integer → `users.id`, **set null** on delete | Null for automatic actions, and for entries whose user was deleted. |
|
||||
| `actor_label` | text | The user's name/email as it was at the time (or `system`), so an entry still reads correctly after the account is gone. |
|
||||
| `category` | text NOT NULL | Free text. In use: `server`, `integration`, `dns`, `settings`, `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`. |
|
||||
| `category` | text NOT NULL | Free text. In use: `server`, `integration`, `dns`, `settings`, `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`, `alert_ticket`. |
|
||||
| `action` | text NOT NULL | `create`, `update`, `delete`, `start`, `stop`, … — free text. |
|
||||
| `target_type`, `target_id` | text | What it happened to. `target_id` is text so it can hold any kind of ID; there's no foreign key. |
|
||||
| `detail` | text | JSON, free-form context (what changed, names, counts). Secrets are never put here. |
|
||||
@@ -405,6 +406,25 @@ Consistency findings someone looked at and decided are fine.
|
||||
| `reason`, `created_by` | text | |
|
||||
| `created_at` | text NOT NULL | |
|
||||
|
||||
#### `alert_tickets`
|
||||
|
||||
What the "open an osTicket ticket for an alert" feature remembers about each problem it has seen, so one problem opens one ticket however many
|
||||
checks see it. A row is one *occurrence*: when an alert clears and later returns for good, that is a new row.
|
||||
|
||||
| Column | Type | Notes |
|
||||
|---|---|---|
|
||||
| `id` | integer PK | |
|
||||
| `alert_key` | text NOT NULL, indexed | The alert's id as the Alerts page shows it (e.g. `disk:server:3:/`). Not a foreign key — alerts aren't stored. |
|
||||
| `status` | text NOT NULL | `pending` (seen, not yet in enough checks in a row), `open` (a ticket was opened), `baseline` (already there when the feature was switched on, left alone). |
|
||||
| `seen_count` | integer NOT NULL, default 1 | Checks in a row it has been seen while pending. |
|
||||
| `integration_id` | integer → `integrations.id`, **set null** | The osTicket integration the ticket went to. |
|
||||
| `ticket_number` | text | osTicket's own number; null unless `open`. |
|
||||
| `grouped` | bool NOT NULL, default 0 | Part of a summary ticket that covers several alerts (they share a number). |
|
||||
| `severity`, `message` | text NOT NULL | What the alert said when it was recorded. |
|
||||
| `first_seen_at`, `last_seen_at` | text NOT NULL | ISO. |
|
||||
| `ticketed_at` | text | ISO; when the ticket was opened. |
|
||||
| `cleared_at` | text | ISO; null while the alert is still active. Rows cleared more than 180 days ago are deleted. |
|
||||
|
||||
## What's stored inside the JSON columns
|
||||
|
||||
| Column | Shape |
|
||||
@@ -446,6 +466,7 @@ that were never changed aren't stored; the app fills in defaults when reading.
|
||||
| `display` | `dateFormat`, `timeFormat`, `pageSize`. |
|
||||
| `providerColors`, `integrationColors` | Badge colours, by provider / integration type. |
|
||||
| `consistency` | `excludedRanges` — addresses the Consistency and IP Addresses pages ignore. Default `["172.16.0.0/12"]` (Docker's networks). |
|
||||
| `alertTickets` | Opening osTicket tickets for alerts: `enabled`, `integrationId`, `severities`, `categories`, `requesterName`/`requesterEmail`, `topicId`, `priorityId`, `notifyStaff`, `existingProblems`, `confirmChecks`, `summaryAbove`, `reopenAfterMinutes`. Edited under Settings → Alert tickets. The API address and key are on the osTicket integration, not here. |
|
||||
| `nameGenerator` | `themes` — the Generator's server-name lists: `[{ "id", "label", "names": [...], "lastImport"? }]`. Edited under Settings → Names. |
|
||||
|
||||
Rows whose key starts with **`_internal:`** are scheduler bookkeeping, not
|
||||
@@ -455,6 +476,7 @@ settings, and aren't part of the app's settings object:
|
||||
|---|---|
|
||||
| `_internal:secretCheckLastRunDate`, `tailscaleKeyCheckLastRunDate`, `dockerUpdateCheckLastRunDate`, `proxmoxBackupCheckLastRunDate`, `pbsVerificationCheckLastRunDate` | The date a daily check last ran, so a restart doesn't repeat it (or skip it). |
|
||||
| `_internal:logRetentionLastRunAt` | When the log purge last ran. |
|
||||
| `_internal:alertTicketsBaselineDone`, `_internal:alertTicketsLastRun` | Whether the alert-ticket starting line has been recorded since the feature was switched on, and JSON for the last check's result. |
|
||||
| `_internal:healthActiveConditions`, `_internal:automationActiveConditions` | JSON: the problems currently active, so each is announced once and again when it clears, and survives a restart. |
|
||||
|
||||
## What happens on delete
|
||||
@@ -464,6 +486,7 @@ settings, and aren't part of the app's settings object:
|
||||
| a **server** | Its `scheduled_tasks`, `server_links` and `server_ports` are deleted with it. Port forwards that pointed at it stay, with `server_id` cleared. |
|
||||
| a **DNS provider** | Its cached zones and records are deleted. |
|
||||
| an **integration** or **DNS provider** | The credential row it used is deleted by the app (not by the database). |
|
||||
| an **integration** used for alert tickets | `alert_tickets.integration_id` is cleared; the history stays. |
|
||||
| an **integration credential** | The integration / provider using it keeps existing, with `credential_id` cleared. |
|
||||
| a **user** | Their audit entries stay; `actor_user_id` is cleared and `actor_label` keeps the name. |
|
||||
| a **Proxmox integration** that servers are linked to | Those servers keep existing and lose their Proxmox link (all four `proxmox_*` columns). The app does this before deleting; the database alone would refuse — see the next section. |
|
||||
|
||||
+21
-2
@@ -116,8 +116,8 @@ the dashboard views themselves load fine.
|
||||
reading osTicket's own MySQL/MariaDB database directly, the same way osTicket's own admin panel does internally.
|
||||
This makes it the only integration in this app that isn't a REST API.
|
||||
- **Actions used:** read-only — a single `SELECT` joining the ticket, status, priority, department, staff, team,
|
||||
and requester tables for every ticket whose status is in the "open" state. Nothing here can create, update, or
|
||||
close a ticket.
|
||||
and requester tables for every ticket whose status is in the "open" state. Nothing in this part can create,
|
||||
update, or close a ticket — opening tickets is the separate, optional API described below.
|
||||
- **Required access:** a MySQL/MariaDB user with **read-only (`SELECT`) access to the osTicket database only** —
|
||||
never reuse osTicket's own application database user, which has full read/write access. Create one with
|
||||
something like:
|
||||
@@ -148,6 +148,25 @@ the dashboard views themselves load fine.
|
||||
a field looks wrong, tell us what happened and we'll adjust — this one has had less real-world exposure than
|
||||
every other integration listed here.
|
||||
|
||||
**Optional: opening tickets for alerts** (Settings → Alert tickets)
|
||||
|
||||
- **Config fields:** Ticket API address (optional), Ticket API key (optional, stored encrypted like the database
|
||||
password), Allow self-signed certificate (ticket API). Leave them empty and the integration works as before.
|
||||
- **Auth:** osTicket's own HTTP API: `POST <address>/api/tickets.json` with the key in an `X-API-Key` header.
|
||||
- **Make the key in osTicket:** Admin Panel → Manage → API Keys → Add. Tie it to the IP address osTicket sees this
|
||||
app's requests come from (behind Docker or a reverse proxy that is the host's or proxy's address, not the
|
||||
container's — check osTicket's log if it refuses) and tick **Can create tickets**. osTicket refuses a key from any
|
||||
other address, which is the most common reason a test ticket fails.
|
||||
- **What is sent:** one ticket per problem — name and email you set under Settings → Alert tickets, a subject, the
|
||||
problem's text and a link back to this app, optionally a help topic and priority id — with `autorespond` off (the
|
||||
"user" is this app, so an acknowledgement would only bounce) and osTicket's own staff alert on or off as you choose.
|
||||
- **What it can't do:** close, reopen, or comment on a ticket — osTicket's API has no such endpoint. A ticket opened
|
||||
here is yours to close in osTicket.
|
||||
- **Not verified against a real osTicket** — built from osTicket's published API documentation and tested against a
|
||||
stand-in server that checks what is sent (the key header, the JSON fields, the message encoding, and how each
|
||||
answer — created, refused key, bad request, redirect — is handled). If osTicket rejects a ticket, "Send a test
|
||||
ticket" shows the reason it gave.
|
||||
|
||||
### phpIPAM
|
||||
|
||||
- **Config fields:** phpIPAM URL, API app ID, App token
|
||||
|
||||
+28
-4
@@ -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
|
||||
|
||||
@@ -308,6 +308,14 @@ It checks live (a recent result is reused for a minute; "Check now" forces a
|
||||
fresh one), and anything it couldn't read is called out at the top rather than
|
||||
quietly treated as fine.
|
||||
|
||||
**Alert tickets** (Settings → Alert tickets, admin only) opens a ticket in osTicket for an alert, through osTicket's own API. Every 15 minutes the
|
||||
problems on the Alerts page are looked at, and one that is new and has lasted two checks in a row gets one ticket — never a second for the same problem,
|
||||
and never one for something under a maintenance window or about osTicket itself. You choose which severities and kinds count (critical and warning by
|
||||
default), and the Alerts page shows the ticket number on each alert that has one. If many problems appear at once — a network drop that makes thirty
|
||||
things look down — they become one summary ticket instead of thirty. Problems already there when you switch it on are left alone unless you ask for
|
||||
tickets for them too. osTicket's API can't close or update a ticket, so once it's open it's yours to close. It needs an API key made in osTicket (tied to
|
||||
this server's IP address, allowed to create tickets), entered on the osTicket integration; "Send a test ticket" checks the whole chain.
|
||||
|
||||
**Maintenance mode** silences alerts about one server, integration, or DNS
|
||||
provider while you work on it (server offline / disk, storage and Synology
|
||||
health, Proxmox backup alerts, Proxmox Backup Server verification alerts, and
|
||||
|
||||
@@ -82,6 +82,10 @@ even further, to admin only:
|
||||
- **Generator**: everyone can use it; the name lists it picks server names from
|
||||
are edited under Settings → Names, which is admin-only (and so is importing
|
||||
names from Skatteverket).
|
||||
- **Alert tickets**: everyone sees which alerts have an osTicket ticket (a
|
||||
badge on the Alerts page, linking to the ticket in osTicket); switching the
|
||||
feature on, choosing what opens a ticket, and sending a test ticket are
|
||||
under Settings → Alert tickets, which is admin-only.
|
||||
- Everything under **Settings** (notification channels, badge colors,
|
||||
display prefs, log retention, backup/restore) is admin-only, matching
|
||||
the page itself being admin-only.
|
||||
|
||||
Reference in new issue
Block a user