Open an osTicket ticket for an alert that lasts

With Settings -> Alert tickets switched on (off by default), every 15 minutes the problems on the
Alerts page are looked at and one that is new and has lasted gets one ticket in osTicket, through
its API (POST api/tickets.json, key in X-API-Key). One problem opens one ticket however many checks
see it; the app remembers what it has seen in a new alert_tickets table (migration 0015).

- Which: critical and warning by default, every kind; severities and kinds are settings.
- A problem must be seen in 2 checks in a row first (1-4, a setting), so a blip that fixes itself,
  like one failed call to an integration, never opens a ticket.
- One ticket per occurrence; a problem that clears and returns within 60 minutes is the same one.
- More than 5 new problems in one check become a single summary ticket.
- Never for alerts under a maintenance window, nor about osTicket itself or its overdue tickets.
- Problems already there when it is switched on are left alone by default (the first check records
  them as a baseline); can be set to ticket them too.
- If osTicket can't be reached nothing is recorded, so the next check retries; if a source couldn't
  be read, a problem isn't treated as gone. Every ticket is audited.

The ticket API address, key (stored encrypted) and self-signed option are optional fields on the
osTicket integration, which otherwise still only reads the database. The settings page can send a
test ticket and run a check now; the Alerts page shows each alert's ticket number, linked to osTicket.

osTicket's API can't close or update a ticket, so a ticket opened here is the end of this app's part
in it. Tested against a stand-in osTicket, not a real one.

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:44 +02:00
1 parent f71756b119
commit 467d1a1a06
14 files changed
+3455 -2

No files matched your search

+45
View File
@@ -107,6 +107,35 @@ export interface NameGeneratorSettings {
themes: NameTheme[];
}
export type AlertTicketSeverity = "critical" | "warning" | "info";
/** Opening an osTicket ticket for an alert. Off until an admin sets it up under Settings → Alert tickets. */
export interface AlertTicketSettings {
enabled: boolean;
/** The osTicket integration whose API (address and key) is used. */
integrationId: number | null;
/** Which severities open a ticket. */
severities: AlertTicketSeverity[];
/** Which kinds of alert (the categories on the Alerts page). Empty means every kind. */
categories: string[];
/** Who the tickets appear to be from. osTicket needs both; the email is where staff replies would go. */
requesterName: string;
requesterEmail: string;
/** osTicket help topic and priority ids, if tickets should land somewhere other than its defaults. */
topicId: number | null;
priorityId: number | null;
/** Let osTicket send its own "new ticket" alert to staff, per its own settings. */
notifyStaff: boolean;
/** Problems already present when this is switched on: left alone ("ignore") or given tickets too ("ticket"). */
existingProblems: "ignore" | "ticket";
/** An alert must be there in this many checks in a row (15 minutes apart) before it opens a ticket, so a blip that fixes itself never does. */
confirmChecks: number;
/** More new alerts than this in one check become a single summary ticket instead of one each. */
summaryAbove: number;
/** An alert that clears and comes back within this many minutes is still the same problem, not a new ticket. */
reopenAfterMinutes: number;
}
export interface AppSettings {
gotify: GotifySettings;
ntfy: NtfySettings;
@@ -121,6 +150,7 @@ export interface AppSettings {
healthChecks: HealthCheckSettings;
consistency: ConsistencySettings;
nameGenerator: NameGeneratorSettings;
alertTickets: AlertTicketSettings;
}
const DEFAULTS: AppSettings = {
@@ -155,6 +185,21 @@ const DEFAULTS: AppSettings = {
// Docker host repeats them. Shown on the Consistency page, where it can be removed if 172.16/12 is used as a real LAN.
consistency: { excludedRanges: ["172.16.0.0/12"] },
nameGenerator: { themes: defaultThemes() },
alertTickets: {
enabled: false,
integrationId: null,
severities: ["critical", "warning"],
categories: [],
requesterName: "Homelab Manager",
requesterEmail: "",
topicId: null,
priorityId: null,
notifyStaff: true,
existingProblems: "ignore",
confirmChecks: 2,
summaryAbove: 5,
reopenAfterMinutes: 60,
},
};
const KEYS = Object.keys(DEFAULTS) as (keyof AppSettings)[];