Problem Management

Problem Management

Problem Management tracks the root cause behind one or more incidents. Where the Tickets module handles individual incidents, a Problem groups the recurring ones, records the root cause and a workaround, flags a known error, and links to the Change that permanently fixes it.

Incidents ask "what's broken for this person?" — a Problem asks "why does this keep happening, and how do we stop it?"

The lifecycle

A problem moves through a settings-managed status flow (defaults):

New → Investigating → Root Cause Identified → Known Error → Resolved → Closed

Mark a problem a known error once a workaround exists, so the service desk can apply that workaround to new incidents while the permanent fix is in progress. Statuses and priorities are managed under Problem Management → Settings (add/edit/colour/default/active), like the other lookups.

Linking incidents

The incident↔problem link works from either side:

• From a ticket — the reading pane has a Problem strip with a Link to problem button, and a Link to problem… action on the ticket right-click menu (works on whichever ticket you right-clicked, even if a different one is open). Both open a searchable picker listing the company's open problems — click one to link, or Create a new problem from this incident in a single step.
• From the problem — Link incident opens a large picker that lists the open incidents in the problem's company (excluding any already linked), with a search box and checkboxes so you can tick several and link them all at once.

Linked incidents are shown in a table (Reference / Subject / Status) with open-in-new-tab and unlink icons; unlinking asks for confirmation (the incident itself isn't deleted). On a multi-company install, an incident and a problem must belong to the same company to be linked.

Linking the fix (a Change)

Use Link change on a problem to connect the Change Management record that implements the permanent fix. Like the incident picker, this opens a searchable, multi-select list of changes. The fix is shown in a table with open/unlink icons (unlink confirms first). This makes the full chain visible — incidents → problem → change — and is stored in the shared change_relations table.

Deep links to a change are standardised on ?change_id=N (matching tickets' ?ticket_id=); the older ?open= / ?change= / ?id= forms still work as aliases.

Notes

Each problem has a Notes journal — a free-text running commentary separate from the structured History. Type a note and click Add; every note records who wrote it and when, listed newest-first. Notes are immutable (no edit/delete) so the journal stays a trustworthy record.

History

A History table logs structured changes to the problem (When / Who / What) — status changes, links added, etc. — distinct from the free-text Notes above.

AI helpers

Both use the Problem AI key (bring your own provider/key, set in Settings):

• Draft root cause — reads the linked incidents and proposes a root cause + workaround for you to review and save. Nothing is saved automatically.
• Detect problems — on the list, scans recent open incidents in the active company and proposes candidate problems (groups that likely share a cause). You confirm a suggestion to create the problem and link those incidents in one go.

Companies (multi-tenancy)

Each problem belongs to a company (taken from your active company when you create it) and is only visible to analysts who can access that company — exactly like tickets. On a single-company install none of this is visible (problems.tenant_id, analystCanAccessProblem()).

Files

• problem-management/ — index.php (list/detail/editor SPA), settings/, help.php, new/, includes/header.php; assets/js/problem-management.js.
• api/problem-management/ — list / get / save / delete; get/save/delete_problem_status + _priority; link_ticket / unlink_ticket / list_linkable_tickets; link_change / unlink_change / list_linkable_changes; add_note; ai_root_cause / ai_suggest_problem.
• Tables: problems, problem_statuses, problem_priorities, problem_tickets, problem_notes, problem_audit (problem↔change link reuses change_relations).
• Module key problems (waffle menu + landing + analyst_modules).

Not yet built (phase 2 ideas)

• i18n — currently English-only plain strings; wire t() + locale files like the other modules.
• Attachments on problems (screenshots, logs, RCA documents).
• Edit / delete own notes, and @mention or note types (e.g. internal vs customer-facing).
• Enforced status state machine (e.g. can't reach Resolved without a recorded root cause) and a resolution field.
• SLA / ageing on problems (time-in-status, target review dates) and a problem dashboard/report.
• Auto-suggest links — surface likely-related open problems on a ticket, and likely-duplicate problems when creating one.
• Notify on link/resolve — tell linked incidents' owners when the parent problem is resolved (and offer to close the incidents).
• Known Error database view — a filtered list of known errors + workarounds for the service desk, surfaced in Tickets/Self-Service.