Repository navigation
Change Risk Policy Developer Guide
How FreeITSM lets an organisation set its own Change risk scale - levels, criteria, results and the matrix between them - without ever changing how an existing change reads. Built for #246 (changelog #2736).
For what it does from a user's point of view, see Change risk policies. The agreed design, with the decisions and why, is Change risk policies - design. How the rest of a change works is in Change Management - Developer Guide.
A rating means nothing without its scale, so a change carries its scale. Every save of a policy is an immutable version; changes.risk_policy_version_id points at the version a change was rated under, and every screen, export and API response draws the change on that version - never on the one in use now. The built-in 5 × 5 is not stored at all: it lives in code, and NULL means it. So an install that never opens the new tab is byte-for-byte what it was, and no row needed migrating.
| File | Job |
|---|---|
includes/changes/risk_policy.php |
The model. ChangeRiskPolicy: the built-in, lookup by company, validation, assessment, versioned saves, history, the page bootstrap |
includes/services/changes.php |
applyCreate() and updateChange() rate through the policy; the re-assessment rule |
includes/changes/approvals.php |
The approval fingerprint counts the scale |
includes/changes/templates.php |
A template remembers its scale; riskPolicyMatches(); check()
|
api/change-management/get_risk_policy.php, save_risk_policy.php
|
The settings tab's two endpoints, behind Cap::CHANGES_RISK_POLICY
|
api/change-management/save_template.php |
Template ratings checked against the policy, scale recorded |
api/change-management/list.php |
Returns risk_policy_version_id for the list and table |
assets/js/change-risk.js |
The screen side. window.ChangeRisk: labels, criteria, results, colours, selects, the guide, the matrix |
assets/js/change-management.js |
The editor: setEditorRiskScale(), reassessRisk(), updateRiskScore()
|
change-management/settings/index.php |
The Risk policy tab, and the template editor's ratings |
change-management/evidence.php, includes/report_packs/blocks_changes.php
|
Evidence text and report colours from the policy |
api/v1/resources/changes.php |
risk.policy on every change; GET /change-risk-policy
|
tests/change-risk-policy.php |
46 checks - see Testing it |
CREATE TABLE IF NOT EXISTS `change_risk_policies` (
`id` INT NOT NULL AUTO_INCREMENT,
`tenant_id` INT NULL,
`current_version_id` INT NULL,
`updated_by_id` INT NULL,
`updated_datetime` DATETIME NULL,
PRIMARY KEY (`id`),
KEY `ix_crp_tenant` (`tenant_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;-
One row per install today,
tenant_id NULL. A company with its own policy later is another row with itstenant_id. -
current_version_id NULL= the built-in. Use built-in sets it back toNULL; the versions stay. -
A plain key on
tenant_id, not a unique one. MySQL treats everyNULLas distinct in a unique index, soUNIQUE (tenant_id)would not stop two install-wide rows. Insteadsave()finds-or-creates the row inside aGET_LOCK(below).
CREATE TABLE IF NOT EXISTS `change_risk_policy_versions` (
`id` INT NOT NULL AUTO_INCREMENT,
`policy_id` INT NOT NULL,
`version_no` INT NOT NULL,
`content` LONGTEXT NOT NULL,
`content_hash` CHAR(64) NOT NULL,
`created_by_id` INT NULL,
`created_datetime` DATETIME NOT NULL,
PRIMARY KEY (`id`),
UNIQUE KEY `uq_crpv_policy_version` (`policy_id`, `version_no`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;-
Never updated. There is no code path that writes to a version after its
INSERT. That is what makes "a change keeps its scale" true. -
version_nocounts per policy; the unique key makes a race between two saves fail rather than produce two "version 3"s.
Two columns on existing tables, both NULL = built-in:
`risk_policy_version_id` INT NULL, -- #246: NULL = the built-in 5 x 5on changes, and the same on change_templates. changes.risk_level widened from VARCHAR(20) to VARCHAR(50), because a policy's words can be longer than Very High. CREATE TABLE IF NOT EXISTS cannot widen an existing column, so Database Verification does it with the same probe-then-MODIFY shape as its other upgrades:
if ($rlLen !== false && (int)$rlLen < 50) {
$conn->exec("ALTER TABLE `changes` MODIFY `risk_level` VARCHAR(50) NULL");Widening a VARCHAR cannot invalidate a row, so it is safe on a live table.
{
"name": "Information security policy",
"likelihood": [ { "label": "gering", "criteria": "..." }, ... ],
"impact": [ { "label": "gering", "criteria": "..." }, ... ],
"results": [ { "label": "gering", "colour": "#16a34a" }, ... ],
"matrix": [ [0, 0, 1, 2], [0, 1, 1, 2], ... ]
}- Levels and results are lowest first. A rating is the 1-based position: likelihood
3islikelihood[2]. -
matrix[l - 1][i - 1]is an index intoresults. Rows are likelihood, columns impact. -
results[n].labelis whatchanges.risk_levelstores.
public static function builtin(): array
{
$band = static fn(int $s): int => $s <= 4 ? 0 : ($s <= 9 ? 1 : ($s <= 15 ? 2 : ($s <= 20 ? 3 : 4)));
$matrix = [];
for ($l = 1; $l <= 5; $l++) {
for ($i = 1; $i <= 5; $i++) $matrix[$l - 1][$i - 1] = $band($l * $i);
}The old bands (≤4 Low, ≤9 Medium, ≤15 High, ≤20 Very High, else Critical) written out once as a 25-cell matrix. From here on the built-in is just another policy: the same assess() reads it. The test proves all 25 cells give exactly what riskLevel() used to.
Its levels and results also carry translation keys, which a saved policy never has:
$out[] = ['label' => ($n + 1) . ' - ' . $w, 'criteria' => '', 'key' => 'rl_' . ($n + 1),
'criteria_key' => 'risk_help_' . ($axis === 'likelihood' ? 'l' : 'i') . ($n + 1)];So the server stores and returns the English words, as before, while the screens show change-management.editor.rl_3 (3 - Medium) and the #231 example criteria in the reader's language. A saved policy's words are the organisation's and are shown as typed.
public static function current(PDO $conn, ?int $tenantId): array
{
if (!self::ready($conn)) return ['version_id' => null, 'version_no' => null, 'content' => self::builtin()];
try {
$s = $conn->prepare(
"SELECT p.current_version_id, v.version_no
FROM change_risk_policies p
LEFT JOIN change_risk_policy_versions v ON v.id = p.current_version_id
WHERE p.tenant_id <=> ? OR p.tenant_id IS NULL
ORDER BY p.tenant_id IS NULL, p.id
LIMIT 1"
);Reading the SQL:
-
p.tenant_id <=> ?is MySQL's null-safe equals:NULL <=> NULLis true, whereNULL = NULLis not. Passingnull(templates, the settings tab) matches the install row. -
OR p.tenant_id IS NULLbrings in the install's row as the fallback. -
ORDER BY p.tenant_id IS NULLsorts0(a company's own row) before1(the install's), so a company's policy wins when it has one. -
LEFT JOINbecausecurrent_version_idmay beNULL- the built-in - which still needs the row.
Every caller passes the change's company, which is why per-company policies later are a settings screen and not a rework: applyCreate() passes $tenantId, updateChange() passes $current['tenant_id']. The test inserts a company row and proves the company gets its own while another company and the install still get the install's.
public static function ready(PDO $conn): bool
{
if (self::$ready !== null) return self::$ready;
try {
$conn->query("SELECT risk_policy_version_id FROM changes LIMIT 0");An upgraded install that has not run Database Verification has none of the new columns. ready() probes once per request; until it is true, current() returns the built-in, updateChange() never writes risk_policy_version_id, list.php selects NULL AS risk_policy_version_id, and the settings tab says to run Verification. Changes keep saving exactly as before.
public static function rating($value, string $field, array $content, string $axis): ?int
{
if ($value === null || $value === '') return null;
$n = self::levels($content, $axis);
if (!is_numeric($value) || (int)$value != $value || (int)$value < 1 || (int)$value > $n) {
throw new ServiceError('validation', 'invalid_field', "'{$field}' must be between 1 and {$n}.");
}
return (int)$value;
}The range comes from the policy, so on the built-in the message is word for word the old one (between 1 and 5). (int)$value != $value refuses 2.5, which the old (int) cast silently truncated.
public static function assess(array $content, ?int $likelihood, ?int $impact): array
{
if ($likelihood === null || $impact === null) return [null, null];
$idx = $content['matrix'][$likelihood - 1][$impact - 1] ?? null;
$label = $idx !== null ? ($content['results'][$idx]['label'] ?? null) : null;
return [$likelihood * $impact, $label];
}TRAP: the score is still likelihood × impact - the API returns it, reports sort by it, the matrix cells show it - but it does not decide the result. The matrix does. On the test's 4 × 4, 1 × 4 scores 4 and is hoch, where banding a 4 would give the lowest result. Never band the score.
In applyCreate(), the policy is fetched first, because a template's values are merged before the ratings are read:
// The risk policy new assessments in this company use (#246).
$policy = ChangeRiskPolicy::current($conn, $tenantId); $ratingsFit = ChangeTemplates::riskPolicyMatches($templateVersion['content'], $policy['version_id']);
foreach ($templateVersion['content']['values'] ?? [] as $col => $val) {
if (!$ratingsFit && in_array($col, ['risk_likelihood', 'risk_impact_score'], true)) continue;Then:
$riskLikelihood = ChangeRiskPolicy::rating($in['risk_likelihood'] ?? null, 'risk_likelihood', $policy['content'], 'likelihood');
$riskImpact = ChangeRiskPolicy::rating($in['risk_impact_score'] ?? null, 'risk_impact_score', $policy['content'], 'impact');
[$riskScore, $riskLevel] = ChangeRiskPolicy::assess($policy['content'], $riskLikelihood, $riskImpact);and after the INSERT, the version - only when something was rated, and never for the built-in:
if ($policy['version_id'] !== null && ($riskLikelihood !== null || $riskImpact !== null)) {
$conn->prepare("UPDATE changes SET risk_policy_version_id = ? WHERE id = ?")->execute([$policy['version_id'], $changeId]);
}An unrated change records no version: its first rating, whenever that is, uses the policy in use then.
This is the part to understand before changing anything. The editor's full-form save sends every field, the ratings included, so "a rating was sent" is not the same as "the analyst re-rated it". For a change on an older version, sending its own ratings back must change nothing; sending different ones moves it to the current policy.
$asSent = static function ($v, ?int $old): bool {
return ($v === null || $v === '') ? $old === null : (is_numeric($v) && (int)$v === $old);
};
$same = (!array_key_exists('risk_likelihood', $in) || $asSent($in['risk_likelihood'], $oldLikelihood))
&& (!array_key_exists('risk_impact_score', $in) || $asSent($in['risk_impact_score'], $oldImpact));
$newVersion = $oldVersion;
if ($rated && $oldVersion !== $policy['version_id']) {
if ($same && empty($in['risk_reassess'])) {
$riskTouched = false; // untouched: it stays on the scale it was rated on
} else {
if (!array_key_exists('risk_likelihood', $in) || !array_key_exists('risk_impact_score', $in)) {
throw new ServiceError('validation', 'invalid_field', t('change-management.risk_policy.err_reassess_both'));
}
$newVersion = $policy['version_id'];
}
} elseif (!$rated) {
$newVersion = $policy['version_id']; // a first rating uses the policy in use now
}| The change | What is sent | Result |
|---|---|---|
| On the current version | anything | Validated on the current scale, as before #246 |
| Not rated yet | a rating | Rated on the current policy, version recorded |
| On an older version | its own ratings back (every full-form save) | Untouched - stays on its scale |
| On an older version | different ratings, both | Re-assessed onto the current policy |
| On an older version | different rating, only one | Refused: one new number beside one old one means nothing |
| On an older version |
risk_reassess: true and both |
Re-assessed even with the same numbers - the editor's Re-assess button sends this |
$asSent compares by value, so "5" from a form and 5 from JSON are the same, and '' means cleared.
Then the ratings are judged on the scale the change is going to be on:
$scale = ChangeRiskPolicy::content($conn, $newVersion);and a move is written and audited:
if ($newVersion !== $oldVersion && ChangeRiskPolicy::ready($conn)) {
$updates[] = 'risk_policy_version_id = ?';
$args[] = $newVersion;
$queueAudit('Risk Policy', ChangeRiskPolicy::describeVersion($conn, $oldVersion), ChangeRiskPolicy::describeVersion($conn, $newVersion));
}The audit row reads Risk Policy: Built-in 5 x 5 → Information security policy (version 1), so the history says why the result changed.
One more condition changed: the score and level used to be rewritten only when a number changed. A re-assessment can keep both numbers and still change the result, because the matrix moved:
if ($newLikelihood !== $oldLikelihood || $newImpact !== $oldImpact || $newVersion !== $oldVersion) {When the risk ratings are material (Settings → Approvals, on by default), a change approved at 3 of 5 and re-assessed to 3 of 4 must need a fresh approval, although the numbers did not change. So the fingerprint includes the version:
if ((in_array('risk_likelihood', $material, true) || in_array('risk_impact_score', $material, true))
&& ($row['risk_policy_version_id'] ?? null) !== null) {
$out['risk_policy_version_id'] = (string)$row['risk_policy_version_id'];
}TRAP: only when the version is not
NULL. Adding the key for built-in changes too would change the hash of every approval round taken before #246, and every approved change would suddenly read "approved an earlier version". With this guard, every existing fingerprint is unchanged - the test computes one before the 4 × 4 is introduced and compares after.
The extra key is not one of CHANGE_MATERIAL_CHOICES, so it does not appear as a tick in Settings, and changeApprovalRound()'s "what changed" list (which only names long fields with revisions) ignores it.
A template's working draft records the scale of its ratings (change_templates.risk_policy_version_id), and a submitted version freezes it into its content:
if (!empty($t['risk_policy_version_id'])) $content['risk_policy_version_id'] = (int)$t['risk_policy_version_id'];Only when it is a saved policy, so a template rated on the built-in freezes exactly the content it always did. Versions frozen before #246 have no key - the built-in.
public static function riskPolicyMatches(array $content, ?int $policyVersionId): bool
{
$own = isset($content['risk_policy_version_id']) ? (int)$content['risk_policy_version_id'] : null;
return $own === $policyVersionId;
}Two places use it:
-
applyCreate()(above) does not copy the ratings onto a change on another scale. -
check()- the pre-authorisation test - refuses when the change's numbers match the template's but its scale does not:
if ($riskFixed && !self::riskPolicyMatches($v['content'], $rowVersion)) {
return ['ok' => false, 'reason' => 'changed', 'version' => $v, 'changed_fields' => $riskFixed];
}Without that, an analyst who typed the template's 5 and 4 again on a four-level scale (4 only, so say 4 and 4) would get a change "matching the recipe" whose risk nobody approved.
save_template.php applies the same untouched-stays-put rule as updateChange(): unchanged ratings keep their version; new ones are validated on the install's policy (current($conn, null) - templates are install-wide) and record it.
public static function save(PDO $conn, array $in, int $actorId, ?int $tenantId = null): int
{
$content = self::normalise($in);
$json = json_encode($content, JSON_UNESCAPED_UNICODE);
$lock = self::lockName($conn);
$conn->prepare("SELECT GET_LOCK(?, 10)")->execute([$lock]);-
normalise()refuses rather than repairs. 2-10 levels per axis, 2-8 results, a label on every one, no two the same (case-insensitively), criteria up to 1,000 characters, a colour matching^#[0-9a-f]{6}$(so nothing but a colour can reach astyleattribute), and every matrix cell set to a valid result index. It rebuilds the content from those fields only, so nothing else sent is ever stored. -
The lock covers find-or-create of the policy row and the next
version_no. Its name includes the database, becauseGET_LOCKnames are per MySQL server and two installs on one server each have a policy 1 - the same TRAP asdsyncLock(). -
The
INSERTand theUPDATEofcurrent_version_idare one transaction, so a policy never points at a version that was rolled back.
The endpoint is api/change-management/save_risk_policy.php: POST only (csrfRequireWriteMethod()), module write access, and Cap::CHANGES_RISK_POLICY, which the manifest marks sensitive - it decides how risky every new change reads.
Every page that draws a risk gets every version with the page:
$data = ['policies' => (object)self::all($conn), 'current' => $cur['version_id'] ?? 0,
'current_no' => $cur['version_no']];
return '<script>window.CM_RISK = ' . json_encode($data, JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_UNESCAPED_UNICODE) . ';</script>';-
Version
0is the built-in. Versions are few and small, so sending them all is simpler than fetching per change, and a list can colour every row on its own version. -
JSON_HEX_TAG: the words are the administrator's, and a label containing</script>would otherwise end the block. -
(object)keeps{"0": ...}an object in JSON even when only the built-in exists.
The change page, the table and the settings page call ChangeRiskPolicy::jsBootstrap() and then load change-risk.js.
function resultFor(p, l, i) {
const row = (p.matrix || [])[l - 1];
const idx = row ? row[i - 1] : undefined;
return idx === undefined ? null : (p.results || [])[idx] || null;
}The browser's copy of the bands, riskLevelForScore(), is gone. There used to be two copies of the banding kept in step by hand (PHP and JS); now both sides read the same matrix from the same content.
function paint(r, solid) {
if (!r) return { cls: '', style: '' };
if (r.key) return { cls: 'risk-' + r.key.replace(/_/g, '-'), style: '' };
const c = /^#[0-9a-f]{6}$/i.test(r.colour || '') ? r.colour : '#94a3b8';
return { cls: 'risk-custom', style: solid ? `background:${c};color:#fff;` : `background:${c}22;color:${c};border:1px solid ${c}66;` };
}A built-in result has a key, so it keeps the old CSS classes (risk-very-high) and looks exactly as before. A policy's result is coloured inline from its own colour - 22 and 66 are 8-digit hex alpha, a 13% tint and a 40% border - after checking the value is a colour again, although the server already did.
function fillSelects(versionId, likelihoodSel, impactSel) {
const p = policy(versionId);The two <select>s in change-management/index.php now hold only Not assessed; the options come from the version being rated on. The #231 guide's table body (#riskGuideRows) is drawn from the same version by guideRows(): the built-in's translated example criteria, or the policy's own label and criteria for each level. For a saved policy the worked example (built-in numbers) is hidden and "these are examples, not a policy" becomes "This is your organisation's risk policy: {name}".
change-management.js keeps one piece of state:
let editorRisk = { version: 0, reassess: false };-
New change:
setEditorRiskScale(ChangeRisk.currentId(), false). - Edit: the change's own version if it is rated, otherwise the current one:
setEditorRiskScale(rated ? (c.risk_policy_version_id || 0) : ChangeRisk.currentId(), false);- When that is not the current version,
#riskOlderPolicyshows "Rated under ... Re-assess to rate it on the policy in use." -
Re-assess empties both ratings and calls
setEditorRiskScale(ChangeRisk.currentId(), true); the save then sendsrisk_reassess: true, which is how the server tells a deliberate re-rating to the same numbers from an untouched save. - A template applied in the editor copies its ratings only when
tpl.risk_policy_version_idmatcheseditorRisk.version, and otherwise says why - the same rule the server applies.
updateRiskScore() reads ChangeRisk.resultFor() on editorRisk.version, so the result beside the fields is always the matrix's.
ChangeRisk.matrix(c) replaces the hard-coded 5 × 5 renderRiskMatrix(). It draws L rows and I columns from the change's version, highest likelihood at the top, and sizes the grid inline because the CSS fixed it at five:
<div class="risk-matrix-grid" style="grid-template-columns: 24px repeat(${I}, ${Math.max(L, I) > 6 ? 32 : 44}px); grid-template-rows: repeat(${L}, ${Math.max(L, I) > 6 ? 32 : 44}px) 20px;">Cells shrink from 44px to 32px past six levels, so a 10 × 10 still fits a phone.
| Where | How |
|---|---|
| Evidence export | Ratings by name and position (gering (1 of 4)), and Risk policy: ... from describeVersion()
|
| Report Packs | The by risk dimension no longer has a SQL CASE of five colours; each group's colour comes from ChangeRiskPolicy::colourFor(), which looks the word up in its own version, then any version |
| Record preview | Unchanged - it shows the stored word |
| Workflows |
change.risk is still the stored word, so conditions keep working; renaming a result in a new version needs workflow conditions updated, and the settings tab says so |
| REST API |
rating() gives the policy's range in the 422; every change's risk gains policy (apiChangeRiskPolicyRef()); GET /change-risk-policy returns the current policy in full. The OpenAPI schemas were edited by hand (never run openapi_fix.php in place) and openapi_check.php passes |
| Feature Bingo |
changes.risk_policy lights when a version has been saved |
| Analyst lifecycle |
change_risk_policies.updated_by_id and change_risk_policy_versions.created_by_id are in analystReferenceRegistry() as history |
-
Never band the score. The result is
matrix[l - 1][i - 1]. Anything new that needs "the risk" readsrisk_level, or callsassess(). -
Never draw a change on the current policy. Use
ChangeRiskPolicy::content($conn, $row['risk_policy_version_id'])(PHP) orChangeRisk.policy(c.risk_policy_version_id)(JS). The current policy is only for new ratings. - Never edit a version. Fix a mistake by saving the next one.
- A full-form save is not a re-assessment. Any new path that writes ratings must keep the untouched-stays-put rule, or every edit of an old change would silently re-read its numbers on the new scale.
- Keep the fingerprint guard. Adding the version to built-in changes' fingerprints would mark every existing approval as out of date.
-
Pass the company. Call
current($conn, $tenantId)with the change's company, nevernull, except for install-wide things (templates, the settings tab today).
tests/change-risk-policy.php:
php tests/change-risk-policy.php
FREEITSM_TEST_DATABASE=<a throwaway database> php tests/change-risk-policy.php
Part 1 needs no database (23 checks): the built-in matches the old bands in all 25 cells; a policy's result comes from its matrix (1 × 4 = hoch); ranges, fractions and blanks; and every refusal normalise() makes - empty cell, cell past the results, missing row, too few or too many levels, a bad colour or one carrying CSS, duplicate names, a result too long for risk_level, no name - each paired with the valid policy being accepted.
Part 2 (23 checks) changes the install's policy while it runs, so it refuses anything but the database named in FREEITSM_TEST_DATABASE. Through ChangesService, on a 4 × 4 that is deliberately not multiply-and-band: a built-in change keeps 5/5/25/Critical and its fingerprint after the 4 × 4 arrives; a new change gets hoch from the matrix; a 5 is refused; an unchanged save leaves an old change alone; one rating is refused; two re-assess it with an audit row; risk_reassess with the same numbers changes the fingerprint; a built-in template is not copied and not pre-authorised on the 4 × 4 (with the control that it still is on its own scale); a company's own policy wins; Use built-in leaves rated changes on their version. Its finally removes its changes, template and versions and puts the policy row back.
It was also checked in a browser on the test install, through the real pages - the change page and matrix on both scales, Re-assess, the table, the settings tab (including a refused save with an empty cell and a real save making version 2) and the template editor - and through the REST API with a real key.
- Change risk policies - the user page
- Change risk policies - design - #246, the decisions
- Change Management - Developer Guide
- Approvals and evidence - 1. Change approvals - the fingerprint
- REST API: Changes
FreeITSM — an open-source IT Service Management platform · github.com/edmozley/freeitsm · MIT licence
- Installation
- ⏰ Scheduled tasks (cron jobs)
-
Architecture
- ↳ 🧹 Root folder tidy (URL routing)
- ↳ 🔗 Database Integrity (FKs & constraints)
- ↳ 🛠️ Database Verification — Developer Guide
- ↳ 🧩 Service Layer (UI + API share code)
- ↳ 🪤 Code traps (the TRAP: comments)
- ↳ 📝 Commenting for the Engineering wiki
- ↳ 🛠️ Engineering wiki scanner - Developer Guide
- ↳ 📊 Service-Layer progress
- 🤝 Contributing (read before a pull request)
- 🧪 Developer tests
- 📄 PDF exports moved to PDFKit (#254)
- AI Providers
- Internationalisation (i18n)
- Timezones & Time Handling
- 📅 Date & Time Formats
- 💱 Currencies
- 🧭 The sidebar (optional module rail)
- 🧩 Preference templates
- 🔀 Display order (modules, Watchtower cards) — Developer Guide
- Theming & Dark Mode
- 🗂️ Recent — getting back to what you were doing
- ⌨️ Command palette (⌘K)
- 🔍 Searching inside tickets
- 📄 Attached documents
-
Mobile‑Friendly
- ↳ 🎫 Mobile: Tickets
- ↳ 💻 Mobile: Assets
- ↳ 📅 Mobile: Calendar
- ↳ 📚 Mobile: Knowledge
- ↳ 🚦 Mobile: Service Status
- ↳ 🗼 Mobile: Watchtower
- ↳ 🧩 Mobile: Problem Management
- ↳ 🔁 Mobile: Change Management
- ↳ 💿 Mobile: Software
- ↳ ✅ Mobile: Tasks
- ↳ 📝 Mobile: Forms
- ↳ 📄 Mobile: Contracts
- ↳ 📄 Mobile: Domains
- ↳ 📄 Mobile: People
- ↳ 🚀 Mobile: Projects
- ↳ 🗂️ Mobile: Files
- ↳ 🎓 Mobile: LMS
- ↳ 🗺️ Mobile: CMDB
- ↳ 🗺️ Mobile: Network Mapper
- ↳ 🧭 Mobile: Process Mapper
- ↳ ⚙️ Mobile: Workflow
- ↳ 🖥️ Mobile: System
- ↳ 📊 Mobile: Reporting
- ↳ 📖 Mobile: System Wiki
- ↳ 🙋 Mobile: Self-Service Portal
- ↳ 🧰 Mobile: Techniques & Tricks
-
Security
- Layer 1 — which modules you can enter
- ↳ 🧩 Module Access Control
- ↳ 🛠️ Module Access — Developer Guide
- ↳ 🔌 Switching modules off
- ↳ 🛠️ Module availability — Developer Guide
- ↳ 📐 Module availability — design (#217)
- Layer 2 — what you can administer
- ↳ 🎭 Roles & Permissions
- ↳ 🛠️ Roles — Developer Guide
- ↳ 🔤 Why capabilities are constants
- Layer 3 — the System module
- ↳ 🔑 Admin Access Control
- Hardening
- ↳ 📄 Security review response 2026-08
- ↳ 🛡️ Security hardening 2026-08
- ↳ 🛠️ Security hardening 2026-08 — Developer Guide
- ↳ 🛡️ Round three — plain English
- ↳ 🛠️ Round three — Developer Guide
- ↳ 🛡️ CSRF protection (S4) — Developer Guide
- Single Sign-On (SSO)
- 🗂️ LDAP & Active Directory
-
🟦 Microsoft Entra ID
- ↳ 📥 Importing people and groups
- ↳ 💻 Intune: assets to their primary user
- ↳ 🏢 Organisation chart
- ↳ 🛠️ Entra directory sync — Developer Guide
- ↳ 🛠️ Entra import - review (#235)
- ↳ 🛠️ Entra follow-ups - review (#237-#240)
- ↳ 🛠️ Intune primary user - review (#236)
- ↳ 🛠️ Intune after an Entra import - review (#334)
- ↳ 🛠️ Intune primary user history - review (#338)
- ↳ 🛠️ Intune asset types - review (#339)
- ↳ 🛠️ Intune scheduled syncs - review (#344)
- ↳ 🛠️ Microsoft 365 in Integrations - review (#352)
- ↳ 🛠️ Organisation chart - reviews (#242, #265)
- 📇 CardDAV contact sync
- Browser Extension
- API Reference
-
🔌 REST API — how it works
- ↳ 📋 Proposal: custom fields, inventory import and change evidence (#194)
- ↳ 🛠️ Custom fields, evidence + inventory - review (#195-#197)
- ↳ 🛠️ Long forms in a task's Work view - review (#198)
- ↳ 🛠️ Empty Procedures fold - review (#247)
- ↳ 🎫 REST API: Tickets
- ↳ 💻 REST API: Assets
- ↳ 🔴 REST API: Problems
- ↳ 🟠 REST API: Changes
- ↳ 📚 REST API: Knowledge
- ↳ ✅ REST API: Tasks
- ↳ 🗄️ REST API: CMDB
- ↳ 📜 REST API: Contracts
- ↳ 🗓️ REST API: Calendar
- ↳ 💿 REST API: Software
- ↳ 🌐 REST API: Domains
- ↳ 🚦 REST API: Service Status
- ↳ ☀️ REST API: Morning Checks
- ↳ 📝 REST API: Forms
- ↳ ⚙️ REST API: Workflow
- ↳ 🏷️ REST API: Cost centres
- ↳ 🏢 REST API: Companies
- ↳ 📒 REST API: Chart of accounts
- ↳ 📁 REST API: Projects
- ↳ 🛡️ API threat protection
- ↳ 🧑💼 REST API: Analysts
- ↳ 🗺️ REST API: Network Mapper
- ↳ 🧭 Using the API docs page
- ↳ 📐 OpenAPI specification
- ↳ ✅ OpenAPI: kept correct
- ↳ 🛠️ Maintaining the catalogue
- Watchtower
-
Tickets
- ↳ Reply subject and replying to one message
- ↳ 🔄 Live updates
- ↳ 🛠️ Watching a ticket - Developer Guide (1 of 2)
- ↳ ✉️ Ticket address suggestions - Developer Guide
- ↳ 🛠️ CSAT delay and reminder - Developer Guide
- ↳ 🛠️ Ticket checklist step types - Developer Guide (1 of 2)
- ↳ 🛠️ Right-click Attach checklist - Developer Guide
- ↳ 🛠️ Checklists in the REST API - Developer Guide
- ↳ 🔗 A ticket's related block and attachments - Developer Guide
- ↳ 🛠️ Inbox.js map — Developer Guide
- ↳ 🛠️ Floating windows & the file viewer — Developer Guide
- ↳ 🛠️ Tickets settings — Developer Guide
- ↳ 📐 Simpler ticket and task forms - design (#218)
- ↳ 🗂️ The ticket workspace
- ↳ 📋 Forms on tickets
- ↳ 📊 The ticket table
- ↳ 📋 Rota copy and paste — Developer Deep Dive
- ↳ ✅ Checklists & SOPs
- ↳ ☑️ Mandatory fields
- ↳ 🧾 Custom ticket fields
- ↳ 🏷️ Ticket categories
- ↳ 🧾 A type for every new ticket
- ↳ 👥 Assigning tickets to a team, and escalation
- ↳ 🏢 One board across every company
- ↳ 🔎 Many companies: searchable lists (#358)
- ↳ 📊 Ticket dashboard — Developer Guide
- ↳ Mailbox Authentication
- ↳ 📤 Email send log
- ↳ ✉️ Emailed reports
- ↳ 📎 Attachment size limits and large emails
-
↳ Basic IMAP mailboxes
- ↳ 📐 Basic IMAP without the PHP extension (#257)
- ↳ 🛠️ Basic IMAP client — Developer Guide
- ↳ 🧪 Basic IMAP client — Testing and verifying
- ↳ 🛠️ Basic IMAP - Sent copy - Developer Guide (#270)
- ↳ 🛠️ Verifying a mail folder — Developer Guide
- ↳ 🛠️ Mailbox providers — Developer Guide
- ↳ 🛠️ How Gmail mail collection works — Developer Guide
- ↳ Email rendering & images
- ↳ SLA Management
- ↳ WhatsApp channel
-
↳
✈️ Telegram channel - ↳ ⭐ CSAT company scope and filters — Developer Guide
- ↳ 👥 Microsoft Teams channel
- ↳ 🗨️ Mattermost channel
- ↳ 💬 Web chat channel
- ↳ 🟣 Slack channel
- ↳ 🔗 Linking tickets
- ↳ ⓘ Record previews
- ↳ 📝 Ticket notes: internal or shared
- ↳ 🗒️ Canned responses
- ↳ ✉️ Limiting replies to particular senders
- ↳ 📨 Telling the analyst a ticket is theirs
- ↳ ✍️ Email signatures
- ↳ 🌐 The public web address
- ↳ 🔢 Ticket numbering
- ↳ 🙋 Raising a ticket for someone else
- ↳ 🔀 Merging tickets
- ↳ 🔒 Confidential tickets
- ↳ 👥 Portal managers
- ↳ 👁 Who has seen a ticket
- ↳ 📜 Reading long tickets
- ↳ ⑂ Splitting tickets
- ↳ ✅ Selecting several tickets
- ↳ 🗂️ The folder pane
- ↳ 🔽 Just my tickets, or no closed ones
- ↳ 🛠️ Snoozing tickets — Developer Guide
- ↳ 👥 Collision detection
- ↳ ⏱️ Time tracking
- ↳ 📄 Case reports - a ticket and its work as one PDF
- ↳ 📅 Scheduled work in your own calendar
- Problem Management
- Tasks
- 🚀 Projects
-
Assets
- ↳ 🛠️ Asset list by type - review (#340)
- ↳ 🏢 Moving an asset between companies
- ↳ 📍 Shared asset locations
- ↳ 🧑💼 Assigning assets to analysts
- ↳ 📆 Warranty and lease alerts
- ↳ 📄 Leases
- ↳ 🔭 Saved table views
- ↳ 🖨️ Recording anything, and importing it
- ↳ 🧩 Asset type layouts
- ↳ 🕒 Inventory freshness
- ↳ 🔗 Linked configuration item
- ↳ 🔌 Connected assets
- ↳ 🔍 Asset review
- ↳ 🏷️ QR asset labels
- ↳ 📋 Who holds what, and handover documents
- ↳ 🖥️ The inventory agent (PowerShell)
- ↳ 🗄️ Proxmox VE servers
- ↳ ☁️ VMware Cloud Director servers
- ↳ 🪟 Hyper-V and Failover Clusters
- ↳ 🔗 Linking equipment to tickets
- ↳ ☑️ Follow-up tasks on a ticket
- Knowledge
- Change Management
- Calendar
- Morning Checks
- Reporting
- Software
-
Forms
- ↳ 🎨 The form designer — Developer Guide
- ↳ 📐 Layout & the grid — Developer Guide
- ↳ 🗂️ Collections — grouping submissions
- ↳ 📄 Submissions as PDFs
- ↳ ⚡ What happens next — a form's own actions
- ↳ 🛠️ Sections & conditional logic — Developer Guide
- ↳ 🛠️ Lookup fields — Developer Guide
- ↳ 🛡️ Catalogue request approvals
- People
- Starters & leavers
- Domains
- 🗂️ Files
- Contracts
- Service Status
- 🔔 Notifications
- 🚨 War Room
- Self-Service Portal
- LMS
- Process Mapper
-
CMDB
- ↳ 🧱 Designing your CMDB
- ↳ 🛠️ CMDB — Developer Guide
- ↳ 🛠️ Impact analysis — Developer Guide
- ↳ 🛠️ Data quality — Developer Guide
- ↳ 🛠️ Record references — Developer Guide
- ↳ 🛠️ CMDB assistant - Developer Guide
- ↳ 🔗 Linked assets
- ↳ 📐 Linking an asset to its CI - design (#201)
- ↳ 📐 Discovery and redundancy-aware impact - design (#199)
- ↳ 🛠️ Relationship wording - review (#297)
- Network Mapper
-
Workflows
- ↳ 🛠️ Workflow engine — Developer Guide
- ↳ 🛠️ Workflows for tasks — Developer Guide
- ↳ 🛠️ Workflow notes on a ticket — Developer Guide
- ↳ 🛠️ Workflow category routing — Developer Guide
- ↳ 📐 Workflows in order, child tickets - design (#304)
- ↳ ⏰ Time-Based Triggers
- ↳ 🪝 Webhooks
- ↳ 💬 Webhook Message Formats
- ↳ 🔒 HTTPS Certificates & CA Bundles
- ↳ 🛠️ SSL Verification — the Global Setting
- ↳ 🐞 Workflow & Webhook Pitfalls
- Issue trackers (Jira, Azure DevOps)
- 📡 Zabbix (monitoring)
- 💬 Microsoft Teams alerts
- 📞 3CX (phone system)
-
System
- ↳ 🛠️ System cards by topic - review (#347)
- ↳ 🟦 Microsoft 365 (Entra ID and Intune)
- ↳ 🛠️ Preferences — Developer Guide
- ↳ 🧹 Maintenance
- ↳ 💾 Storage usage
- ↳ ✉️ Emailed reports
- ↳ 🔎 Finding people in the Analysts list
- ↳ 🚪 When an analyst leaves
- ↳ 🛠️ System → Branding — Developer Guide
- ↳ 🩺 Page health (D019) — Developer Guide
- ↳ ⭐ Feature Bingo
- ↳ 📍 Locations
- ↳ 🏷️ Cost centres
- ↳ 📒 Chart of accounts
- ↳ 📷 Photo Album
- ↳ Demo Data
- ↳ 🛠️ Demo Data — Developer Guide
-
Overview
- ↳ 📊 Progress tracker
- ↳ Concepts & vocabulary
- ↳ Email routing & mailboxes
- ↳ Settings: global vs per-company
- ↳ Users & self-service
- ↳ Staff cross-company access
- ↳ One company supporting another
- ↳ 🏢 One board across every company
- ↳ Worked examples
- ↳ Pitfalls & gotchas
- ↳ Scope: what it's for
- ↳ 🛠️ Developer Guide (make a module multi-company)
- ↳ 🗄️ Case study: CMDB (a linked graph)
- ↳ 🧪 Test harness (prove it's isolated)
- What this is
-
🐞 Bugs resolved
- ↳ 💱 #386 Project stuck in an old currency
- ↳ 🖥️ #393 Header ran off the screen
- ↳ 🧩 #392 Project dialogs shared element ids
- ↳ 🖼️ #391 Knowledge images from your computer
- ↳ 🕗 #375 REST API wall-clock times
- ↳ 📅 #374 Calendar popup ran off the screen
- ↳ 🏢 #373 All companies: Changes, CMDB, Starters
- ↳ 🏢 #356 Assets People and All companies
- ↳ 🎓 #366 LMS demo data would not import
- ↳ 🔔 #362/#365 Team handover showed only a name
- ↳ 🗄️ #369 Inbox empty until Database Verification
- ↳ 🪆 #360 Links opened inside the ticket
- ↳ 🔗 #354 Workspace Links missed tasks
- ↳ 🔒 Task company checks in the API (5.5.0)
- ↳ 🔒 Asset holders through the API (5.4.0)
- ↳ 🔒 Files folder delete did not check inside (5.4.0)
- ↳ 🔒 The Intune tab did not check the company
- ↳ 📂 #332 Files viewer would not open
- ↳ 📎 #333 Note attachments downloaded
- ↳ 🪝 #326/#327 Form webhook Full record
- ↳ 📄 #325 Form PDF download failed
- ↳ 🔁 Small fixes in 5.1.0
- ↳ 🔁 CMDB relationships read backwards (5.1.0)
- ↳ 🔁 #301 CSAT delay was never applied
- ↳ 🔁 #281 Comments imported from Jira never arrived
- ↳ 🔁 #288 A change failed to open with Enforce approvals on
- ↳ 📚 Long non-Latin articles never got an embedding
- ↳ 🎫 #280 Email lookups scanned the whole table
- ↳ ✅ #266 Dragging a task told nobody
- ↳ 📚 #255 Article previews showed HTML codes
- ↳ 📚 #252 A link to a Knowledge article did not open
- ↳ 📄 #254 PDFs could not print Polish
- ↳ 📚 #250 Clicking a folder left the open article on screen
- ↳ 🎫 #260 The dashboard cog did nothing
- ↳ 🎫 #248 A department rule never matched on four routes
- ↳ 🔒 A directory account could be matched to someone else
- ↳ 🎫 #244 Reply went to the assigned analyst
- ↳ 🔒 Mailbox sign-in was not checked
- ↳ 🔒 Four weaknesses around signing in
- ↳ 🔒 A lookup answer could name any record
- ↳ 🎫 #227 A mailbox could not be deleted
- ↳ 🎫 #226 A picture on a note could not be closed
- ↳ 💻 #222 The Assets page never loaded in 4.3.0
- ↳ ⚙️ #214 A "contains" condition did not match capitals
- ↳ ⚙️ #216 A workflow email from a chosen mailbox always failed
- ↳ 🐳 The Docker image was missing PHP extensions
- ↳ 🌐 A failed DNS lookup read as a missing record
- ↳ 🔒 A link could change data
- ↳ 🔒 Access outlived its removal
- ↳ 🔒 Knowledge articles could run scripts
- ↳ 🔒 Knowledge writes ignored permissions
- ↳ 🔒 Company boundaries (Oct 2026)
- ↳ 🔒 Smaller gaps (Oct 2026)
- ↳ 🔒 Escaped text could leave its attribute
- ↳ 🔒 Task descriptions were not cleaned
- ↳ 🔒 Task documents ignored company scope
- ↳ 🔒 Repeating tasks ignored company scope
- ↳ 📬 #183 Mailbox checks overlapped
- ↳ 🌐 #188 Transfer lock shown off when unknown
- ↳ ✅ #184 Subtask names and Overdue
- ↳ 🧩 #186 Teams: the buttons did nothing
- ↳ 🔒 Text in a change could run script
- ↳ 🔒 AI settings changed without the AI permission
- ↳ 🚪 #178 Deleting an analyst failed
- ↳ 🎫 A team with no departments showed 0 tickets
- ↳ 🚀 Projects: adding a phase did nothing on Save
- ↳ 🔒 Leavers could still sign in
- ↳ 🖼️ Logo and courses broke on Apache with PHP-FPM
- ↳ 🔢 Chat tickets ignored your ticket numbering
- ↳ 📅 Dates shown as a dash, or in server time
- ↳ 🔒 Assets → Users showed people from other companies
- ↳ 🔒 Restricted analysts could read other modules' data
- ↳ 🖼️ Replies with a picture in the thread failed to send
- ↳ 📎 Reply attachments never reached the customer
- ↳ 🛠️ Outbound email attachments — Developer Guide
- ↳ 🔑 A global SSO provider was missing from the portal
- ↳ 🔀 Behind a proxy, the SSO redirect said http
- ↳ ✏️ The portal tagline moved when you saved it
- ↳ 🎨 The portal settings screen forgot what you saved
- ↳ 🛡️ The approvals inbox said "Error" and nothing else
- ↳ 📄 A table's answers were missing from the PDF
- ↳ ◉ A single-select column let you tick every option
- ↳ 📐 The portal ignored a form's field widths
- ↳ 📋 The tasks board stopped taking clicks
- ↳ 🗂️ #121 The index list is out of date after upgrading
- ↳ 📅 #133 The calendar subscription was empty
- ↳ 📋 #131 Tasks always reopened on the board
- ↳ 💥 #129 Every page returned HTTP 500 after upgrading
- ↳ 🐳 #127 A PHP warning above the System page
- ↳ 🕐 #126 Notes stamped with the server's clock
- ↳ 🌍 Storing every date in UTC
- ↳ 🚪 The portal was down for everyone signed in
- ↳ ⚙️ #120 Workflow notes could never be written
- ↳ ⚙️ #123 Three errors when running Database Verification
- ↳ 📝 #122 The description box was a stub in the corner
- ↳ 💣 Demo data deleted real accounts
- ↳ 🔐 #117 Sign-in redirected to the wrong address
- ↳ 🎨 #108 The priority dot was invisible
- ↳ ⏱️ #116 Time logged from the right-click menu
- ↳ 🔑 #114 API keys refused by our own guard
- ↳ 🗂️ #110 Assigning a task told nobody
- ↳ 🚪 #107 Signed out while still working
- ↳ 📎 #103 "Share with Requester" reached nobody
- ↳ 🔍 #102 Search found nothing for hyphens
- ↳ 🪟 #101 Source code editor opened behind
- ↳ ☑️ #88 Subtasks could not be ticked off
- ↳ 💻 #84 Asset deep link selected nothing
- ↳ 🎫 #79 A new ticket arrived with no status
- ↳ 📧 #79 A ticket from email did not say so
- ↳ 🔔 #78 Bell opened to nothing
- ↳ 📬 #77 Mail only collected from Inbox
- ↳ 🔐 #74 The default password could not be changed
- ↳ 🚦 #70 Renaming an impact level
- ↳ 📤 #67 App-only mailboxes could not send
- ↳ 📭 #45 Verify only ever worked for Microsoft
- ↳ 📭 #45 IMAP reported as not authenticated
- ↳ ✉️ An email template stopped escaping itself
- ↳ 🕐 The portal dashboard showed the wrong time
- ↳ 🔢 The folder said 99 and the list showed 96