From 96c93ef9243961cd08d89edc3f59a4201cb4a74c Mon Sep 17 00:00:00 2001 From: Bobban Rydh Date: Wed, 7 Oct 2026 23:41:46 +0200 Subject: [PATCH] Add the Alert tickets settings page, and show each alert's ticket on the Alerts page Settings -> Alert tickets: switch it on, choose the osTicket integration (only ones with a ticket API set up can be chosen), who the tickets come from, help topic and priority, which severities and kinds, how long a problem must last, when many become one summary ticket, how long a return counts as the same problem, and what to do about problems already there. Buttons to send a test ticket and to check now, and a line saying what the last check did. Server messages (a missing integration, a refused key) are shown as they are. The Alerts page shows "Ticket #123" on an alert that has one, linking to it in osTicket, and a Ticket column in the CSV export. Co-Authored-By: Claude Sonnet 5.5 --- web/src/App.tsx | 2 + web/src/api/client.ts | 45 +++ web/src/pages/Alerts.tsx | 18 +- web/src/pages/Privacy.tsx | 4 + web/src/pages/Settings.tsx | 1 + .../pages/settings/AlertTicketSettings.tsx | 304 ++++++++++++++++++ 6 files changed, 372 insertions(+), 2 deletions(-) create mode 100644 web/src/pages/settings/AlertTicketSettings.tsx diff --git a/web/src/App.tsx b/web/src/App.tsx index 983f350..527418a 100644 --- a/web/src/App.tsx +++ b/web/src/App.tsx @@ -39,6 +39,7 @@ import CacheSettings from "./pages/settings/CacheSettings"; import LogSettings from "./pages/settings/LogSettings"; import BackupSettings from "./pages/settings/BackupSettings"; import NameSettings from "./pages/settings/NameSettings"; +import AlertTicketSettings from "./pages/settings/AlertTicketSettings"; import AppShell from "./layout/AppShell"; import DialogHost from "./components/DialogHost"; import { setDateTimeSettings } from "./utils/date"; @@ -163,6 +164,7 @@ export default function App() { } /> } /> } /> + } /> } /> } /> } /> diff --git a/web/src/api/client.ts b/web/src/api/client.ts index dadf364..f4df9bb 100644 --- a/web/src/api/client.ts +++ b/web/src/api/client.ts @@ -409,6 +409,45 @@ export interface AlertItem { link: string | null; /** Under a maintenance window: still a real problem, but its notifications are held back. */ silenced: boolean; + /** The osTicket ticket opened for it, if one was. */ + ticket?: { number: string | null; url: string | null; grouped: boolean; openedAt: string | null } | null; +} + +export type AlertTicketSeverity = "critical" | "warning" | "info"; + +export interface AlertTicketSettings { + enabled: boolean; + integrationId: number | null; + severities: AlertTicketSeverity[]; + categories: string[]; + requesterName: string; + requesterEmail: string; + topicId: number | null; + priorityId: number | null; + notifyStaff: boolean; + existingProblems: "ignore" | "ticket"; + confirmChecks: number; + summaryAbove: number; + reopenAfterMinutes: number; +} + +export interface AlertTicketRunSummary { + at: string; + skipped?: "disabled" | "busy"; + error?: string; + ticketsOpened: number; + alertsCovered: number; + baseline: number; + pending: number; + cleared: number; + failed: number; +} + +export interface AlertTicketOverview { + settings: AlertTicketSettings; + integrations: { id: number; name: string; enabled: boolean; ticketApiReady: boolean }[]; + categories: { value: string; label: string }[]; + status: { lastRun: AlertTicketRunSummary | null; open: number; pending: number; baseline: number; baselinePending: boolean }; } export interface AlertsReport { @@ -1062,6 +1101,12 @@ export const api = { alerts: { list: (refresh = false) => request(`/api/alerts${refresh ? "?refresh=1" : ""}`), }, + alertTickets: { + get: () => request("/api/alert-tickets"), + update: (patch: Partial) => request("/api/alert-tickets", { method: "PUT", body: JSON.stringify(patch) }), + test: () => request<{ ok: boolean; ticketNumber: string | null }>("/api/alert-tickets/test", { method: "POST" }), + run: () => request<{ summary: AlertTicketRunSummary; status: AlertTicketOverview["status"] }>("/api/alert-tickets/run", { method: "POST" }), + }, ports: { agent: () => request("/api/ports/agent"), forwards: { diff --git a/web/src/pages/Alerts.tsx b/web/src/pages/Alerts.tsx index 7e2b061..d5d24b7 100644 --- a/web/src/pages/Alerts.tsx +++ b/web/src/pages/Alerts.tsx @@ -73,8 +73,8 @@ export default function Alerts(_props: { user: CurrentUser }) { function exportCsv() { downloadCsv( "alerts.csv", - ["Severity", "Category", "Source", "Alert", "Silenced"], - (sorted ?? []).map((a) => [SEVERITY[a.severity].label, CATEGORY_LABELS[a.category], a.source, a.message, a.silenced ? "yes" : "no"]), + ["Severity", "Category", "Source", "Alert", "Silenced", "Ticket"], + (sorted ?? []).map((a) => [SEVERITY[a.severity].label, CATEGORY_LABELS[a.category], a.source, a.message, a.silenced ? "yes" : "no", a.ticket ? (a.ticket.number ?? "opened") : ""]), ); } @@ -222,6 +222,20 @@ export default function Alerts(_props: { user: CurrentUser }) { silenced )} + {a.ticket && + (() => { + const label = a.ticket.number ? `Ticket #${a.ticket.number}` : "Ticket opened"; + const title = a.ticket.grouped ? "Part of one ticket that covers several problems that appeared together" : "A ticket was opened for this in osTicket"; + return a.ticket.url ? ( + + {label} + + ) : ( + + {label} + + ); + })()} ))} diff --git a/web/src/pages/Privacy.tsx b/web/src/pages/Privacy.tsx index 59f1030..601f204 100644 --- a/web/src/pages/Privacy.tsx +++ b/web/src/pages/Privacy.tsx @@ -226,6 +226,10 @@ export default function Privacy() { {outbound && outbound.integrationTypes.length > 0 ? ` (${outbound.integrationTypes.join(", ")})` : ""} — API calls to systems you configured, to read status and, when someone with permission asks, to act (start a VM, run a template…). +
  • + osTicket tickets — only if an admin has switched on Settings → Alert tickets: for a problem that has lasted, the text of the alert + (which server or integration, what is wrong), a link back to this app, and the requester name and email set there go to your osTicket's API. +
  • DNS providers {outbound && outbound.dnsProviderTypes.length > 0 ? ` (${outbound.dnsProviderTypes.join(", ")})` : ""} — zones and records are read diff --git a/web/src/pages/Settings.tsx b/web/src/pages/Settings.tsx index a15aba8..bd06c00 100644 --- a/web/src/pages/Settings.tsx +++ b/web/src/pages/Settings.tsx @@ -6,6 +6,7 @@ const SUB_NAV = [ { to: "/settings/badges", label: "Badges" }, { to: "/settings/display", label: "Display" }, { to: "/settings/tags", label: "Tags" }, + { to: "/settings/alert-tickets", label: "Alert tickets" }, { to: "/settings/names", label: "Names" }, { to: "/settings/cache", label: "Cache" }, { to: "/settings/logs", label: "Logs" }, diff --git a/web/src/pages/settings/AlertTicketSettings.tsx b/web/src/pages/settings/AlertTicketSettings.tsx new file mode 100644 index 0000000..5f00395 --- /dev/null +++ b/web/src/pages/settings/AlertTicketSettings.tsx @@ -0,0 +1,304 @@ +import { useEffect, useMemo, useState } from "react"; +import { Link } from "react-router-dom"; +import { api, type AlertTicketOverview, type AlertTicketRunSummary, type AlertTicketSettings as Settings, type AlertTicketSeverity } from "../../api/client"; +import { formatDateTime } from "../../utils/date"; +import { formatAgo } from "../../utils/duration"; +import { readableError } from "../../utils/errors"; + +const SEVERITIES: { value: AlertTicketSeverity; label: string; hint: string }[] = [ + { value: "critical", label: "Critical", hint: "A server down, a disk nearly full, a failed backup, something expired" }, + { value: "warning", label: "Warning", hint: "Something about to expire, an integration failing" }, + { value: "info", label: "Info", hint: "Updates waiting, monitors that can't be matched — rarely worth a ticket" }, +]; + +/** Blank means "not set"; anything else must be a whole number. */ +function optionalNumber(text: string): number | null { + const n = Number(text); + return text.trim() === "" || !Number.isInteger(n) || n < 1 ? null : n; +} + +function describeRun(run: AlertTicketRunSummary): string { + if (run.skipped === "disabled") return "Switched off."; + if (run.skipped === "busy") return "A check was already running."; + const parts = [`${run.ticketsOpened} ticket${run.ticketsOpened === 1 ? "" : "s"} opened${run.ticketsOpened > 0 ? ` for ${run.alertsCovered} alert${run.alertsCovered === 1 ? "" : "s"}` : ""}`]; + if (run.pending > 0) parts.push(`${run.pending} waiting to last long enough`); + if (run.baseline > 0) parts.push(`${run.baseline} already there, left alone`); + if (run.cleared > 0) parts.push(`${run.cleared} cleared`); + if (run.failed > 0) parts.push(`${run.failed} couldn't be opened`); + return `${parts.join(", ")}.`; +} + +export default function AlertTicketSettings() { + const [overview, setOverview] = useState(null); + const [draft, setDraft] = useState(null); + const [error, setError] = useState(null); + const [notice, setNotice] = useState(null); + const [busy, setBusy] = useState<"save" | "test" | "run" | null>(null); + + function show(next: AlertTicketOverview) { + setOverview(next); + setDraft(next.settings); + } + + useEffect(() => { + api.alertTickets + .get() + .then(show) + .catch((err) => setError(readableError(err))); + }, []); + + const dirty = useMemo(() => overview !== null && draft !== null && JSON.stringify(overview.settings) !== JSON.stringify(draft), [overview, draft]); + + if (!overview || !draft) { + return error ?
    {error}
    :
    Loading…
    ; + } + + const set = (patch: Partial) => { + setDraft({ ...draft, ...patch }); + setNotice(null); + }; + const toggle = (list: T[], value: T) => (list.includes(value) ? list.filter((v) => v !== value) : [...list, value]); + + async function save() { + setBusy("save"); + setError(null); + setNotice(null); + try { + show(await api.alertTickets.update(draft!)); + setNotice("Saved."); + } catch (err) { + setError(readableError(err)); + } finally { + setBusy(null); + } + } + + async function sendTest() { + setBusy("test"); + setError(null); + setNotice(null); + try { + const res = await api.alertTickets.test(); + setNotice(`A test ticket was opened in osTicket${res.ticketNumber ? ` (#${res.ticketNumber})` : ""}. You can close it there.`); + } catch (err) { + setError(readableError(err)); + } finally { + setBusy(null); + } + } + + async function checkNow() { + setBusy("run"); + setError(null); + setNotice(null); + try { + const res = await api.alertTickets.run(); + setOverview({ ...overview!, status: res.status }); + if (res.summary.error) setError(res.summary.error); + setNotice(describeRun(res.summary)); + } catch (err) { + setError(readableError(err)); + } finally { + setBusy(null); + } + } + + const chosen = overview.integrations.find((i) => i.id === draft.integrationId); + const { status } = overview; + + return ( + <> + {error &&
    {error}
    } + {notice &&
    {notice}
    } + +
    +
    +

    Open a ticket in osTicket when something goes wrong

    +
    + +
    +
    +
    +

    + Every 15 minutes the problems on the Alerts page are checked, and one that is new and has lasted gets a ticket. One problem opens + one ticket, however many checks see it. Problems under a maintenance window never do. osTicket's API can't close or update a + ticket, so the ticket is yours from then on: close it in osTicket when it is dealt with. The Alerts page shows which alerts have one. +

    +
    +
    + Set this up in osTicket first. Under Admin Panel → Manage → API Keys add a key, tie it to this server's IP address (the one osTicket + sees requests come from), and tick Can create tickets. Then enter the address and the key on the osTicket integration under{" "} + Integrations. +
    +
    + +
    +
    + + + {overview.integrations.length === 0 &&
    There is no osTicket integration yet. Add one under Integrations.
    } + {chosen && !chosen.enabled &&
    That integration is switched off.
    } +
    +
    + +
    +
    + + set({ requesterName: e.target.value })} /> +
    +
    + + set({ requesterEmail: e.target.value })} /> +
    osTicket needs one for every ticket. Replies from staff would go here.
    +
    +
    + + set({ topicId: optionalNumber(e.target.value) })} /> +
    +
    + + set({ priorityId: optionalNumber(e.target.value) })} /> +
    +
    + +
    +
    +
    +
    + +
    +
    +

    Which problems

    +
    +
    +
    +
    +
    Severity
    + {SEVERITIES.map((s) => ( + + ))} +
    +
    +
    Kind
    + + {draft.categories.length > 0 && ( +
    + {overview.categories.map((c) => ( + + ))} +
    + )} +
    Problems with osTicket itself never open a ticket — it would go to the thing that is down.
    +
    + +
    + + +
    So a blip that fixes itself, like one failed call to an integration, never opens a ticket.
    +
    +
    + +
    + More than + set({ summaryAbove: Math.min(50, Math.max(1, Number(e.target.value) || 1)) })} /> + new +
    +
    …in one check become a single ticket listing them all, so one outage doesn't fill the queue.
    +
    +
    + +
    + set({ reopenAfterMinutes: Math.min(1440, Math.max(0, Number(e.target.value) || 0)) })} /> + minutes +
    +
    A problem that clears and returns this fast is the same one, not a new ticket. After that, it is.
    +
    + +
    +
    Problems already there when this is switched on
    + + +
    +
    +
    +
    + +
    +
    +

    What it has done

    +
    + +
    +
    +
    + {status.lastRun ? ( +
    + Last check {formatAgo(status.lastRun.at)}: {describeRun(status.lastRun)} + {status.lastRun.error &&
    {status.lastRun.error}
    } +
    + ) : ( +
    No check has run yet.
    + )} +
    + Right now: {status.open} problem{status.open === 1 ? "" : "s"} with a ticket, {status.pending} waiting to last long enough, {status.baseline} already there and left alone. + {status.baselinePending && " The next check records what is wrong at that point as the starting line, without opening tickets for it."} +
    +
    +
    + +
    + + + {dirty && You have unsaved changes.} +
    + + ); +}