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. |
|
||||
|
||||
Reference in new issue
Block a user