Incidents

What is an Incident?

An incident is an unplanned interruption to an IT service or a reduction in the quality of an IT service. The goal of incident management is to restore normal service operation as quickly as possible and minimise the adverse impact on business operations.

In FlowOS, every incident is a record in the incidents table. It has a lifecycle of statuses, an assigned team and engineer, links to related problems and changes, SLA tracking, a full timeline of comments and work notes, and integration with CMDB configuration items.

Customer Feedback (External Incidents)

FlowOS tracks customer-reported feedback as external incidents — standard incidents with asourceType of external. This eliminates a separate case-management module while giving customer feedback all the benefits of the incident workflow: SLA tracking, assignment, escalation, CMDB linking, and audit history.

External-Incident Fields

Close the Loop Flow

When an external incident is resolved, agents can send a closure notification email to the customer. The email contains a link to /feedback/ack/[token] where the customer confirms resolution or reopens with a reason. The incident detail page has a Close the Loop tab that shows notification status, acknowledgment status, and a reply-to-customer box.

Feedback Collection Channels

• •
• /settings/feedback-channels — Channel Hub: overview of all channels with incident counts
• •
• /settings/feedback-channels/qr — QR codes for physical locations
• •
• /settings/feedback-channels/widget — Embeddable web widget (JavaScript snippet)
• •
• /settings/feedback-channels/whatsapp — WhatsApp Business API integration
• •
• /settings/feedback-channels/google-reviews — Google Reviews auto-sync
• •
• /feedback/[qrToken] — Public feedback form (no auth required)
• •
• /mobile/feedback — In-app mobile feedback form
• •
• /settings/feedback-routing — Auto-routing rules (condition → team/priority)
• •
• /settings/feedback-team-mapping — Default team per feedback type
• •
• /settings/feedback-categories — Custom category taxonomy
• •
• /settings/feedback-alerts — Negative feedback alert rules
• •
• /analytics/feedback — Feedback analytics dashboard
• •
• /onboarding/feedback — 5-step guided setup wizard

Field Reference

The following table lists every field on an incident record, its data type, whether it is required, who can set it, and what it does.

Priority Matrix

Priority is automatically computed from the combination of severity and urgency. It is used for visual display and sorting in list views. SLA policies are driven by severity independently.

Status Lifecycle

Timeline & Comments

Every incident has an append-only timeline of events and comments. There are three comment types:

POST /api/itsm/incidents/:id/comments
{
  "type": "work_note",
  "body": "Checked DB slow query log — top query is a full-table scan on audit_events. Adding index now.",
  "attachments": ["att_01HZ..."]   // optional file attachment IDs
}

Role-Based Field Access

Not all fields are writable by all roles. The table below shows field-level write access.

◐ limited means the field is writable only when the user is the assignee or within their assigned team.

SLA Integration

When an incident is created, FlowOS automatically finds the matching SLA policy based onseverity and category. The sla object is populated with computed deadlines. SLA timers are paused when status = monitoring and stop on resolved.

"sla": {
  "policyId":           "slap_enterprise_p1",
  "policyName":         "Enterprise P1 SLA",
  "firstResponseDue":   "2026-06-01T09:45:00Z",   // 15 min from creation
  "resolutionDue":      "2026-06-01T10:30:00Z",   // 1 hr from creation
  "firstResponseMet":   true,
  "firstResponseAt":    "2026-06-01T09:38:00Z",
  "resolutionMet":      false,
  "breached":           false,
  "remainingMs":        1234567,
  "pausedMs":           0
}

Built-in Automations

These automations run automatically on every workspace without configuration:

• •Auto-assign — If an assignment rule matches the incident's category + team, it auto-assigns to the matching team.
• •SLA timer start — Starts immediately on record creation.
• •First response capture — Sets firstResponseAt on the first public comment from the assigned team.
• •Reopen counter — Increments reopenCount each time a resolved incident is set back to open.
• •Duplicate detection — If two incidents share the same title and same P1 severity within 5 minutes, FlowOS surfaces a duplicate warning.
• •Audit events — Every field change, comment, and status transition writes an immutable audit event.
• •P1 on-call escalation — When an incident with priority=critical or priority=p1 is created, the current on-call engineer (from oncall_schedules) is automatically assigned and receives an in-app + email alert. If the engineer does not acknowledge (move status to in_progress or beyond) within 15 minutes, the team manager is notified.

Events Emitted

API Quick Reference

Example: Create a P1 incident

POST /api/v1/itsm/incidents
Authorization: Bearer $TOKEN
X-Workspace: acme

{
  "title": "Checkout service returning 503 — all regions",
  "description": "All checkout requests failing with 503 since 09:28 UTC. Error rate 100%.",
  "severity": "P1",
  "urgency": "high",
  "category": "software",
  "source": "monitoring",
  "impactedServices": ["checkout", "payments"],
  "cmdbItems": ["ci_checkout_service", "ci_payment_gateway"],
  "assignedTeam": "platform",
  "tags": ["checkout", "503", "production"]
}