GLPI KEDB

A known-error database that surfaces workarounds mid-ticket, and turns recurring incidents into problem candidates a human decides on.

Compared to KnowbaseItem and Problem

	KnowbaseItem	Problem	KnownError
Nature	Reference material	The investigation	The operational answer while a fix is pending
Lifecycle	None	Open → resolved	known → workaround available → fix in progress → resolved/retired
Retiring	N/A	Closing the Problem	Explicit; stops surfacing, keeps its history
Reaches a ticket	Only if someone goes looking	Manual link	Automatically, matched by category/CI/symptom
Points back at incidents	No	Is the record of one	Nightly, from ticket clusters

The workaround field is the primary operational element; the remaining fields provide context and linkage.

Features

• KnownError itemtype — title, symptom, root cause, workaround (all rich text), status, one optional linked Problem, links to N ITIL categories, N configuration items and N free-text software names, entity scope, view and use counters.

  

• Ticket banner, central interface only. Matches by ITIL category (walking parent categories), by linked configuration item, and by symptom keyword. Keyword matching is typo-tolerant through glpisearch when that is installed and indexing KnownError, and a LIKE search otherwise.

• Hit log — every shown/used/dismissed event as its own row, per KE and ticket, which is where the stats page comes from. A dismissal is scoped to the ticket rather than the technician. “Used it” puts an editable followup snippet in whatever editor is open; it never posts.

• Deterministic candidate clusterer, always on and with no dependency on any other plugin: same entity + same category, or same entity + same CI, ≥K tickets in the trailing M days, none linked to a Problem yet.

• AI candidate clusterer, gated on glpiai being active, the entity’s own allowlist, and a switch of this plugin’s own. Additive to the deterministic pass, never a replacement.

• Review queue — accept (creates a core Problem, links the member tickets, optionally a stub KnownError) or dismiss with a reason. A dismissed fingerprint is never proposed again.

  

• 5 whys tab on core’s Problem — five ordered why/answer pairs, contributing factors, a countermeasure. Locks when marked complete; unlocking is a click rather than a permission, and is logged.

  

• Stats — KE hit rate (shown/used/dismissed, use rate excluding undecided rows) and candidate accept rate by method.

  

Install

# from the GLPI root — the directory must be named for the plugin key,
# which is not the repository name
git clone https://github.com/bijstaan/glpi-kedb.git plugins/glpikedb
php bin/console plugin:install -u glpi glpikedb
php bin/console plugin:activate glpikedb

Settings

Setup → Plugins → GLPI KEDB. Opens on a status card: KE counts, cron freshness, whether glpisearch is indexing known errors, whether glpiai is active and how many entities pass its gate.

Setting	Default	Notes
Show the banner at all	on
Match by category	on	Walks parent categories too
Match by linked CI	on
Match by symptom keywords	on	glpisearch when it is indexing KnownError, LIKE otherwise
Max known errors per banner	5
Cluster minimum tickets (K)	5
Cluster window in days (M)	14
AI clustering	off	Requires glpiai active, the entity’s gate open, and this switch
AI recent-ticket window	30 days
AI max tickets per entity	300	Cost control

Rights

• plugin_glpikedb_ke — read/create/update/delete/purge, separately grantable at read and update. Authoring known errors.
• plugin_glpikedb_queue — read/update. Triaging the candidate queue.
• The 5-whys tab uses core’s problem right; it is content of the Problem record, not a domain of its own.

Limitations

• The keyword fallback is blunt. Without glpisearch indexing KnownError, symptom matching is a token overlap count against LIKE '%word%' — no typo tolerance, no semantics. It will miss a ticket phrased very differently from the KE. The status card says which mode is active.
• Category and CI matching read the ticket as it currently is. A ticket recategorised after the banner rendered will not re-match until reload.
• AI cluster fingerprints have no growth immunity. The deterministic fingerprint is built from axis criteria, so a dismissed cluster that gains a ticket is not re-proposed. An AI cluster has only the ticket set the model named, so a near-identical later set is a new candidate.
• “Used it” cannot always find an editor. GLPI’s timeline shares one content-named field across the followup, task and solution editors with no stable id. With none open, the workaround text goes to the clipboard with a prompt rather than nowhere.
• The deterministic clusterer reads recent tickets per entity in full on every cron run, with no incremental state. An instance with very high per-entity ticket volume would want that made incremental first.

Tests

tests/matcher.php and tests/clusterer.php are pure PHP — no DB, no GLPI bootstrap:

php tests/matcher.php
php tests/clusterer.php

tests/integration.php needs a live GLPI with the plugin active and creates and cleans up its own fixtures; see tests/run.sh. tests/browser/kedb-check.js drives the full scenario in a browser — banner, View/Used it/Dismiss, the nightly cron turning five similar tickets into a queue candidate, accept → Problem, and the 5-whys lock/unlock/audit round trip — and takes the screenshots above.

Licence

GPL-3.0-or-later, the same licence as GLPI. The plugin is loaded into GLPI’s process and extends its classes, so it is a derivative work. See LICENSE.