Known Error Database (KEDB)

Overview

A known error is a documented root cause and workaround for a recurring problem, published so agents, the self-service portal, and the virtual agent can surface it before someone opens a duplicate ticket. FlowOS stores known errors as their own collection (separate from the Problem record's known_error status — see the note below), with a full publish/expire/retire lifecycle, view/usage counters, and links back to the problem, incidents, CIs, and knowledge article it relates to.

Model Fields

Publish / Expire / Retire Lifecycle

• •draft — Initial status on create. Not visible to portal users.
• •published — Set via the /publish action. Sets publishedAt and publishedBy. Visible to portal/self-service consumers and returned by /match.
• •expired — Set via the /expire action, only allowed from published.
• •retired — Set via the /retire action, allowed from any status. Terminal for the dedicated (portal) route; the base route can still /publish a retired-then-reopened record only if its status is draft/expired/workaround_available.
• •closed — Base route only, via /close, requires closedReason; represents a permanent fix applied. Records closedAt, closedBy, and optionally the change that fixed it.
• •workaround_available — A valid status value accepted by PATCH on the base route, alongside the other statuses. It is treated as a publishable state for the base route’s /publish action, but is not itself set by any lifecycle action.

Numbers are generated with the KE prefix via the shared number-generator utility (e.g. KE-0001), the same mechanism used by other ITSM record types.

Two Route Files

Known errors are served by two Fastify route files mounted at different prefixes. Both operate on the same KnownError collection but serve different audiences:

Base routes — /api/itsm/known-errors

The original agent-facing CRUD surface. Creating or editing a known error requires an ITSM problem role (problem_agent, problem_manager, itil, itsm_manager, itil_admin, or an admin/owner role). It is the only surface with /close (permanent-fix closure) and /apply-to-incident (link the workaround to an incident and add an IncidentTimeline entry). PATCH here allows changing status directly.

Dedicated routes — /api/itsm/known-errors-records

A portal-friendly resource layered on top of the same collection (see the file header comment: "Batch 2A — Known Error Dedicated Routes"). List and get-by-id default to published-only results unless the caller has a privileged role (owner, admin, superadmin, itsm_manager, knowledge_manager). It adds a /match endpoint for finding published known errors that match an incident by title text, category, or CI id — useful for suggesting a workaround while an incident is being filed. Its PATCH deliberately excludes status, publishedAt, and publishedBy from the update payload; status can only move via the /publish and /retire actions, and there is no /close or /apply-to-incident here.

# Create a known error (base route, agent-facing)
POST /api/itsm/known-errors
{
  "title": "Login fails after SSO token refresh",
  "symptoms": "Users see \"session expired\" immediately after SSO redirect.",
  "rootCause": "Token refresh handler drops the tenant claim.",
  "workaround": "Clear browser cookies for the app domain and log in again.",
  "workaroundSteps": ["Log out", "Clear cookies for app.example.com", "Log in again"],
  "relatedProblemId": "665f1a2b3c4d5e6f7a8b9c0d",
  "category": "authentication"
}

# Publish it
POST /api/itsm/known-errors/:id/publish

# Portal: find matches for an incoming incident
GET /api/itsm/known-errors-records/match?q=SSO&category=authentication

API Quick Reference

Base routes — /api/itsm/known-errors

Dedicated (portal) routes — /api/itsm/known-errors-records