Problems API

The Problems API manages IT problems following ITIL: root cause analysis, workaround documentation, a known-error database with automatic matching to tickets, statuses that pause the SLA (ON_HOLD/WAITING_VENDOR), links to other records via the Entity Linking API and closing linked tickets and incidents together (cascading close).

Endpoints Overview

KEDB: The known-error suggestion for a ticket comes from the Tickets API: GET /api/tickets/:id/suggest-known-errors (requires problems.viewOwn). See the Known Error Database section below.

Problem Categories (CRUD)

Category fields: name (1-50), description (≤200), color (#RRGGBB), isActive.

State Machine

Problems have 8 statuses. Enum values are sent and returned in upper case; lower-case values return 400. Status is set via PATCH /:id and requires problems.changeStatus. Reopening a terminal problem (CLOSED/RESOLVED → INVESTIGATING) also goes through PATCH /:id but requires the dedicated problems.reopen permission and a reopenReason (optional reopenNote).

NEW → INVESTIGATING → IDENTIFIED → WORKAROUND → RESOLVED → CLOSED
                  ↕
          ON_HOLD / WAITING_VENDOR  (SLA paused)

• NEW            = Detected, not yet investigated
• INVESTIGATING  = Root cause analysis in progress
• IDENTIFIED     = Root cause known (known error)
• WORKAROUND     = Workaround available
• ON_HOLD        = SLA paused — waiting for internal decision
• WAITING_VENDOR = SLA paused — waiting for external analysis
• RESOLVED       = Permanently resolved (e.g., via change)
• CLOSED         = Closed & archived

Create Problem

Request

POST /api/problems

Input convention: priority and businessImpact are sent in upper case (LOW, MEDIUM, HIGH, CRITICAL); lower-case values return 400. With user auth, reporter is set automatically to the logged-in user; with API-key auth, reporterId is required in the body.

{
  "title": "Database performance degradation during peak hours",
  "description": "Multiple incidents reported slow database queries between 9-11 AM over 5 days.",
  "categoryId": "clx-performance-category",
  "priority": "HIGH",
  "businessImpact": "HIGH",
  "impactDescription": "500+ users experience slow response times during peak hours",
  "affectedUsers": 500,
  "affectedServices": ["Database", "API", "Reporting"],
  "symptoms": ["Query time +300%", "Connection pool exhaustion", "API timeouts"],
  "assignedGroupId": "clx-db-team-group",
  "tags": ["performance", "database", "peak-hours"]
}

Response (201 Created)

{
  "id": "clx...",
  "problemNumber": "PRB-2026-000015",
  "title": "Database performance degradation during peak hours",
  "status": "NEW",
  "priority": "HIGH",
  "businessImpact": "HIGH",
  "category": { "id": "clx...", "name": "Performance", "color": "#f59e0b" },
  "reporter": { "id": "clx...", "name": "John Doe", "email": "john@example.com" },
  "assignedGroup": { "id": "clx...", "name": "Database Team" },
  "affectedServices": ["Database", "API", "Reporting"],
  "symptoms": ["Query time +300%", "..."],
  "createdAt": "2026-01-27T16:00:00.000Z"
}

Fields

Create from Incidents (Problem from Incidents / PIR)

POST /api/problems/from-incidents

Creates a problem from multiple selected incidents, auto-links all of them and writes activities on both sides. Requires problems.create AND incidents.linkToProblems.

{
  "incidentIds": ["clx-inc-1", "clx-inc-2"],
  "title": "Recurring database performance pattern",
  "description": "Five incidents over two weeks with identical symptoms.",
  "categoryId": "clx-performance-category",
  "priority": "HIGH",
  "businessImpact": "HIGH",
  "impactDescription": "Peak-hour degradation across multiple services",
  "affectedUsers": 500,
  "originType": "FROM_INCIDENTS"
}

originType: FROM_INCIDENTS (default) or FROM_PIR (post-incident review from a major incident). Affected incident agents receive a notification (PROBLEM_CREATED_FROM_INCIDENTS / _PIR).

Known Error Database (KEDB)

A problem with a documented rootCause and/or workaround (typically status IDENTIFIED or WORKAROUND) is a "known error". Eviworx matches known errors automatically — no manual tagging required:

Matching combines full-text search, typo-tolerant similarity search and category matching, and works for German and English text. Additionally, KB articles can be linked to the problem (linkedArticles) for self-service documentation.

// GET /api/tickets/:id/suggest-known-errors
[
  {
    "problemId": "clx...",
    "problemNumber": "PRB-2026-000015",
    "title": "Database performance degradation during peak hours",
    "status": "WORKAROUND",
    "workaround": "Daily VACUUM ANALYZE at 6 AM",
    "relevanceScore": 0.87
  }
]

Root Cause Analysis Workflow

All steps run via PATCH /api/problems/:id (status change: problems.changeStatus). Example:

# 1. Start investigation
PATCH /api/problems/:id   { "status": "INVESTIGATING" }

# 2. Record root cause (Known Error)
PATCH /api/problems/:id   { "status": "IDENTIFIED",
  "rootCause": "Missing index on tickets.createdAt (500k+ rows → full table scans)" }

# 3. Document workaround → matches open tickets, sends KNOWN_ERROR_SUGGESTION
PATCH /api/problems/:id   { "status": "WORKAROUND",
  "workaround": "Daily VACUUM ANALYZE at 6 AM. 80% fewer timeouts." }

# 4. Permanent solution: link the change, then resolve
POST /api/linking/problems/:id/link-change   { "changeId": "clx-change-id" }
PATCH /api/problems/:id   { "status": "RESOLVED",
  "resolution": "Index added via CHG-2026-000042. Query times back to <500ms.",
  "resolutionCode": "FIXED_BY_CHANGE" }

# 5. Close (checks linked tickets/incidents → cascading close)
PATCH /api/problems/:id   { "status": "CLOSED", "confirmPartialClose": true }

Timeline Entries

POST /api/problems/:id/timeline

{
  "type": "investigation",
  "message": "Analyzed slow query logs. Found missing index on large table."
}

• type (required — only general, investigation, workaround, resolution; any other value is a 400) and message (required) — the route accepts no further fields. The response is the created entry; system activities (status changes etc.) are written by the server itself and carry their own types.
• Conversation types general / investigation / workaround / resolution trigger a notification to assignee/group.
• A closed problem does not accept notes (400 PROBLEM_ALREADY_CLOSED); reopen it first.
• Permission: problems.addTimeline OR edit rights on this problem; visibility is checked first.

Update Problem

PATCH /api/problems/:id

Partial update. Edit authority: problems.editAll OR (problems.editOwn as reporter/assignee). Additional permissions per field: any status change → problems.changeStatus; (re)assignment incl. unassign → problems.assign. Optimistic locking via version (conflict → 409).

• Updatable: title, description, status, priority, categoryId, businessImpact, impactDescription, affectedUsers, assignedToId, assignedGroupId, symptoms, affectedServices, tags, rootCause, workaround, resolution, resolutionCode, linkedChangeIds, resolvedAt, closedAt, version
• confirmPartialClose – Confirm closing even if some linked tickets are not closable due to mailbox access

Impact Tree, Cascading Close & Unified Timeline

• GET /:id/impact-tree – Direct tickets + linked incidents (with their tickets, 2-hop) + SLA info + access checks. Basis for the close dialog.
• GET /:id/unified-timeline – Aggregates own timeline + activities of linked tickets + incidents (limit/offset).

When a problem is closed, accessible linked tickets/incidents are closed in cascade; the result is returned as cascadingClose in the update response.

Linking to Other Entities

Problems are linked to incidents, changes, tickets, assets and KB articles. Linking itself is bundled in a central linking domain (/api/linking); the links appear on the problem as tickets, linkedIncidents, linkedChanges, linkedAssets and linkedArticles. (Changes can additionally be set directly via PATCH linkedChangeIds.)

Statistics

GET /api/problems/stats

Returns counts per status (RBAC-filtered by viewAll/viewOwn) for the overview cards.

Delete Problem

DELETE /api/problems/:id   → 204 No Content

Soft-delete, critical action (problems.delete, audited; revoking the permission takes effect immediately). A problem with active links to tickets, changes or KB articles cannot be deleted (400 PROBLEM_HAS_ACTIVE_LINKS); remove those links first. Linked incidents do not block deletion. Delete and restore also check visibility of the problem: whoever may not see it gets 404, so its existence is not revealed. Restoring via POST /:id/restore requires problems.restore plus problems.viewDeleted.

List & Filters

GET /api/problems?f.status=INVESTIGATING&f.priority=HIGH&page=1&per=20

RBAC-filtered (viewAll/viewOwn). Response:

{
  "data": [ /* problems */ ],
  "pagination": { "page": 1, "limit": 20, "total": 137, "totalPages": 7, "hasMore": true }
}

Problem vs. Incident