Skip to content

Open-source status page, incident response and uptime monitoring

slack maintenance (#1937)

Thibault Le Ouayfeeb99de3877
diff --git a/apps/server/src/routes/rpc/services/maintenance/index.ts b/apps/server/src/routes/rpc/services/maintenance/index.ts
index 12a266773..5693a06e7 100644
--- a/apps/server/src/routes/rpc/services/maintenance/index.ts
+++ b/apps/server/src/routes/rpc/services/maintenance/index.ts
@@ -71,7 +71,7 @@ interface ValidatedPageComponents {
* Helper to validate page component IDs belong to the workspace and same page.
* Accepts an optional transaction to ensure atomicity with subsequent operations.
*/
-async function validatePageComponentIds(
+export async function validatePageComponentIds(
pageComponentIds: string[],
workspaceId: number,
tx: DB | Transaction = db,
@@ -119,7 +119,7 @@ async function validatePageComponentIds(
* Helper to update page component associations for a maintenance.
* Accepts an optional transaction to ensure atomicity.
*/
-async function updatePageComponentAssociations(
+export async function updatePageComponentAssociations(
maintenanceId: number,
pageComponentIds: number[],
tx: DB | Transaction = db,
@@ -169,7 +169,7 @@ function validateDateRange(
/**
* Helper to validate page exists in workspace.
*/
-async function validatePageExists(
+export async function validatePageExists(
pageId: number,
workspaceId: number,
tx: DB | Transaction = db,
@@ -189,7 +189,7 @@ async function validatePageExists(
* Helper to send maintenance notifications to page subscribers.
* Uses the subscription dispatcher for component-aware filtering.
*/
-async function sendMaintenanceNotification(params: {
+export async function sendMaintenanceNotification(params: {
maintenanceId: number;
limits: Limits;
}) {
diff --git a/apps/server/src/routes/slack/agent.ts b/apps/server/src/routes/slack/agent.ts
index 7fc3aca71..d21b207bc 100644
--- a/apps/server/src/routes/slack/agent.ts
+++ b/apps/server/src/routes/slack/agent.ts
@@ -16,18 +16,22 @@ interface AgentResult {
function buildSystemPrompt(workspaceName: string): string {
return `You are the OpenStatus assistant for workspace "${workspaceName}".
-You help teams create and manage status reports through Slack.
+You help teams create and manage status reports and maintenance windows through Slack.
IMPORTANT: You have NO knowledge of this workspace's data. NEVER guess or make up status pages, components, or reports. ALWAYS call the appropriate tool first to get real data.
- Questions about pages or components -> call listStatusPages
- Questions about reports -> call listStatusReports
+- Questions about maintenances -> call listMaintenances
- Creating a report -> call listStatusPages first, then createStatusReport
+- Scheduling maintenance -> call listStatusPages first, then createMaintenance
Capabilities:
- Create status reports on status pages (createStatusReport)
- Publish progress updates to existing reports (addStatusReportUpdate)
- Edit report metadata like title or components (updateStatusReport)
- List active status reports and status pages
+- Schedule maintenance windows (createMaintenance)
+- List upcoming maintenance windows (listMaintenances)
Lifecycle: createStatusReport once -> addStatusReportUpdate repeatedly -> resolved.
- "provide an update", "we found the cause", "resolve it" -> addStatusReportUpdate
@@ -44,7 +48,13 @@ Guidelines:
- When tagged in a thread, synthesize the full thread into a status report draft.
- Status progression: investigating -> identified -> monitoring -> resolved
- Be concise. Use Slack mrkdwn formatting (*bold*, _italic_).
-- For any mutation, always call the tool so the user sees a confirmation.`;
+- For any mutation, always call the tool so the user sees a confirmation.
+
+Maintenance scheduling:
+- Parse natural language dates into ISO 8601 format. Convert relative dates like "next Friday from 2-3 PM" into proper ISO 8601 timestamps.
+- If the user doesn't specify a timezone, default to UTC and mention that in your response.
+- The "from" time must be before the "to" time.
+- Write a professional maintenance message describing what will happen during the window.`;
}
function convertThreadToMessages(
diff --git a/apps/server/src/routes/slack/blocks.ts b/apps/server/src/routes/slack/blocks.ts
index 0efdb33a1..4891c4f28 100644
--- a/apps/server/src/routes/slack/blocks.ts
+++ b/apps/server/src/routes/slack/blocks.ts
@@ -186,11 +186,68 @@ export function buildConfirmationBlocks(
});
break;
}
+ case "createMaintenance": {
+ const { title, message, from, to, pageId, pageComponentIds } =
+ action.params;
+ blocks.push({
+ type: "section",
+ text: {
+ type: "mrkdwn",
+ text: `*Schedule Maintenance*\n\n*Title:* ${title}\n*From:* ${formatDate(from)}\n*To:* ${formatDate(to)}\n*Page ID:* ${pageId}${
+ pageComponentIds?.length
+ ? `\n*Components:* ${pageComponentIds.join(", ")}`
+ : ""
+ }\n*Message:* ${message}`,
+ },
+ });
+ blocks.push({ type: "divider" });
+ blocks.push({
+ type: "actions",
+ elements: [
+ {
+ type: "button",
+ text: { type: "plain_text", text: "Approve", emoji: true },
+ action_id: `approve_${actionId}`,
+ style: "primary",
+ },
+ {
+ type: "button",
+ text: {
+ type: "plain_text",
+ text: "Approve & Notify",
+ emoji: true,
+ },
+ action_id: `approve_notify_${actionId}`,
+ style: "primary",
+ },
+ {
+ type: "button",
+ text: { type: "plain_text", text: "Cancel", emoji: true },
+ action_id: `cancel_${actionId}`,
+ style: "danger",
+ },
+ ],
+ });
+ break;
+ }
}
return blocks;
}
+function formatDate(iso: string): string {
+ const d = new Date(iso);
+ if (Number.isNaN(d.getTime())) return iso;
+ return d.toLocaleString("en-US", {
+ weekday: "short",
+ month: "short",
+ day: "numeric",
+ hour: "numeric",
+ minute: "2-digit",
+ timeZoneName: "short",
+ });
+}
+
function capitalize(s: string): string {
return s.charAt(0).toUpperCase() + s.slice(1);
}
diff --git a/apps/server/src/routes/slack/confirmation-store.ts b/apps/server/src/routes/slack/confirmation-store.ts
index 49fb546e3..a2c9c4dac 100644
--- a/apps/server/src/routes/slack/confirmation-store.ts
+++ b/apps/server/src/routes/slack/confirmation-store.ts
@@ -47,11 +47,24 @@ const resolveStatusReportActionSchema = z.object({
}),
});
+const createMaintenanceActionSchema = z.object({
+ type: z.literal("createMaintenance"),
+ params: z.object({
+ title: z.string(),
+ message: z.string(),
+ from: z.string(),
+ to: z.string(),
+ pageId: z.number(),
+ pageComponentIds: z.array(z.string()).optional(),
+ }),
+});
+
const actionSchema = z.discriminatedUnion("type", [
createStatusReportActionSchema,
addStatusReportUpdateActionSchema,
updateStatusReportActionSchema,
resolveStatusReportActionSchema,
+ createMaintenanceActionSchema,
]);
const pendingActionSchema = z.object({
diff --git a/apps/server/src/routes/slack/handler.ts b/apps/server/src/routes/slack/handler.ts
index 62bb1322a..7c88f94b4 100644
--- a/apps/server/src/routes/slack/handler.ts
+++ b/apps/server/src/routes/slack/handler.ts
@@ -243,5 +243,7 @@ function getConfirmationText(action: PendingAction["action"]): string {
return `Update Status Report${action.params.title ? `: ${action.params.title}` : ""}`;
case "resolveStatusReport":
return "Resolve Status Report";
+ case "createMaintenance":
+ return `Schedule Maintenance: ${action.params.title}`;
}
}
diff --git a/apps/server/src/routes/slack/interactions.ts b/apps/server/src/routes/slack/interactions.ts
index ba929b249..973e5e673 100644
--- a/apps/server/src/routes/slack/interactions.ts
+++ b/apps/server/src/routes/slack/interactions.ts
@@ -1,11 +1,18 @@
import { db, eq } from "@openstatus/db";
import {
+ maintenance,
page,
statusReport,
statusReportUpdate,
} from "@openstatus/db/src/schema";
import { WebClient } from "@slack/web-api";
import type { Context } from "hono";
+import {
+ sendMaintenanceNotification,
+ updatePageComponentAssociations as updateMaintenanceComponentAssociations,
+ validatePageComponentIds as validateMaintenanceComponentIds,
+ validatePageExists,
+} from "../rpc/services/maintenance";
import {
getStatusReportById,
sendStatusReportNotification,
@@ -122,6 +129,20 @@ export async function handleSlackInteraction(c: Context) {
return c.json({ ok: true });
}
+async function getPageUrl(pageId: number): Promise<string | null> {
+ const statusPage = await db
+ .select({ slug: page.slug, customDomain: page.customDomain })
+ .from(page)
+ .where(eq(page.id, pageId))
+ .get();
+
+ if (!statusPage) return null;
+
+ return statusPage.customDomain
+ ? `https://${statusPage.customDomain}`
+ : `https://${statusPage.slug}.openstatus.dev`;
+}
+
async function getReportUrl(pageId: number, reportId: number): Promise<string> {
const statusPage = await db
.select({ slug: page.slug, customDomain: page.customDomain })
@@ -361,5 +382,83 @@ async function executeAction(
});
break;
}
+
+ case "createMaintenance": {
+ const {
+ title,
+ message,
+ from,
+ to,
+ pageId: maintenancePageId,
+ pageComponentIds: maintenanceComponentIds,
+ } = action.params;
+
+ const fromDate = new Date(from);
+ const toDate = new Date(to);
+ if (fromDate >= toDate) {
+ throw new Error("Start time must be before end time");
+ }
+
+ const newMaintenance = await db.transaction(async (tx) => {
+ await validatePageExists(maintenancePageId, workspaceId, tx);
+
+ const validated = maintenanceComponentIds?.length
+ ? await validateMaintenanceComponentIds(
+ maintenanceComponentIds,
+ workspaceId,
+ tx,
+ )
+ : { componentIds: [], pageId: null };
+
+ if (
+ validated.pageId !== null &&
+ validated.pageId !== maintenancePageId
+ ) {
+ throw new Error(
+ `pageId ${maintenancePageId} does not match the page (${validated.pageId}) that the selected components belong to`,
+ );
+ }
+
+ const record = await tx
+ .insert(maintenance)
+ .values({
+ workspaceId,
+ pageId: maintenancePageId,
+ title,
+ message,
+ from: fromDate,
+ to: toDate,
+ })
+ .returning()
+ .get();
+
+ if (validated.componentIds.length > 0) {
+ await updateMaintenanceComponentAssociations(
+ record.id,
+ validated.componentIds,
+ tx,
+ );
+ }
+
+ return record;
+ });
+
+ if (notify) {
+ await sendMaintenanceNotification({
+ maintenanceId: newMaintenance.id,
+ limits,
+ });
+ }
+
+ const maintenancePageUrl = await getPageUrl(maintenancePageId);
+
+ await slack.chat.update({
+ channel: channelId,
+ ts: messageTs,
+ text: `:white_check_mark: Maintenance *${title}* scheduled${notify ? " and subscribers notified" : ""}.${maintenancePageUrl ? `\n<${maintenancePageUrl}|View status page>` : ""}`,
+ blocks: [],
+ });
+ break;
+ }
}
}
diff --git a/apps/server/src/routes/slack/tools/create-maintenance.ts b/apps/server/src/routes/slack/tools/create-maintenance.ts
new file mode 100644
index 000000000..196d61b0f
--- /dev/null
+++ b/apps/server/src/routes/slack/tools/create-maintenance.ts
@@ -0,0 +1,31 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+export function createCreateMaintenanceTool() {
+ return tool({
+ description:
+ "Schedule a maintenance window on a status page. Parse natural language dates into ISO 8601 format (e.g. 'next Friday 2-3 PM' -> proper ISO strings). The maintenance will be shown to the user for confirmation before publishing.",
+ inputSchema: z.object({
+ title: z.string().describe("Short title for the maintenance window"),
+ message: z
+ .string()
+ .describe(
+ "Professional maintenance message for the public status page",
+ ),
+ from: z
+ .string()
+ .describe("Start time in ISO 8601 format (e.g. 2025-03-14T14:00:00Z)"),
+ to: z
+ .string()
+ .describe("End time in ISO 8601 format (e.g. 2025-03-14T15:00:00Z)"),
+ pageId: z.number().describe("ID of the status page to post on"),
+ pageComponentIds: z
+ .array(z.string())
+ .optional()
+ .describe("IDs of affected page components (optional)"),
+ }),
+ execute: async (input) => {
+ return { needsConfirmation: true as const, params: input };
+ },
+ });
+}
diff --git a/apps/server/src/routes/slack/tools/index.ts b/apps/server/src/routes/slack/tools/index.ts
index 360f3a39d..91ff1c065 100644
--- a/apps/server/src/routes/slack/tools/index.ts
+++ b/apps/server/src/routes/slack/tools/index.ts
@@ -1,6 +1,8 @@
import type { Workspace } from "@openstatus/db/src/schema/workspaces/validation";
import { createAddStatusReportUpdateTool } from "./add-status-report-update";
+import { createCreateMaintenanceTool } from "./create-maintenance";
import { createCreateStatusReportTool } from "./create-status-report";
+import { createListMaintenancesTool } from "./list-maintenances";
import { createListStatusPagesTool } from "./list-status-pages";
import { createListStatusReportsTool } from "./list-status-reports";
import { createResolveStatusReportTool } from "./resolve-status-report";
@@ -14,5 +16,7 @@ export function createTools(workspace: Workspace) {
addStatusReportUpdate: createAddStatusReportUpdateTool(),
updateStatusReport: createUpdateStatusReportTool(),
resolveStatusReport: createResolveStatusReportTool(),
+ listMaintenances: createListMaintenancesTool(workspace.id),
+ createMaintenance: createCreateMaintenanceTool(),
};
}
diff --git a/apps/server/src/routes/slack/tools/list-maintenances.ts b/apps/server/src/routes/slack/tools/list-maintenances.ts
new file mode 100644
index 000000000..1208bcdb5
--- /dev/null
+++ b/apps/server/src/routes/slack/tools/list-maintenances.ts
@@ -0,0 +1,55 @@
+import { and, asc, db, desc, eq, gt } from "@openstatus/db";
+import { maintenance } from "@openstatus/db/src/schema";
+import { tool } from "ai";
+import { z } from "zod";
+
+export function createListMaintenancesTool(workspaceId: number) {
+ return tool({
+ description:
+ "List maintenance windows for this workspace. By default returns only upcoming maintenances. Use this to check existing scheduled maintenance.",
+ inputSchema: z.object({
+ filter: z
+ .enum(["upcoming", "all"])
+ .optional()
+ .describe(
+ "Filter: 'upcoming' for future maintenances (default), 'all' for everything",
+ ),
+ }),
+ execute: async ({ filter = "upcoming" }) => {
+ const conditions = [eq(maintenance.workspaceId, workspaceId)];
+ if (filter === "upcoming") {
+ conditions.push(gt(maintenance.from, new Date()));
+ }
+
+ const records = await db
+ .select({
+ id: maintenance.id,
+ title: maintenance.title,
+ message: maintenance.message,
+ from: maintenance.from,
+ to: maintenance.to,
+ pageId: maintenance.pageId,
+ })
+ .from(maintenance)
+ .where(and(...conditions))
+ .orderBy(
+ filter === "upcoming"
+ ? asc(maintenance.from)
+ : desc(maintenance.from),
+ )
+ .limit(20)
+ .all();
+
+ return {
+ maintenances: records.map((r) => ({
+ id: r.id,
+ title: r.title,
+ message: r.message,
+ from: r.from.toISOString(),
+ to: r.to.toISOString(),
+ pageId: r.pageId,
+ })),
+ };
+ },
+ });
+}
diff --git a/apps/server/src/routes/slack/tools/tools.test.ts b/apps/server/src/routes/slack/tools/tools.test.ts
index d935361cc..5c4041d00 100644
--- a/apps/server/src/routes/slack/tools/tools.test.ts
+++ b/apps/server/src/routes/slack/tools/tools.test.ts
@@ -18,7 +18,9 @@ describe("createTools", () => {
const tools = createTools(mockWorkspace);
expect(Object.keys(tools).sort()).toEqual([
"addStatusReportUpdate",
+ "createMaintenance",
"createStatusReport",
+ "listMaintenances",
"listStatusPages",
"listStatusReports",
"resolveStatusReport",