Skip to content

PR 378 Knowledge Migration API

Ed Mozley edited this page Nov 19, 2026 · 1 revision

🚚 PR #378 Knowledge migration API - what it adds, and what I fixed before merging

GitHub PR #378 by @Dr4inder, for #377 Β· Knowledge Β· REST API Β· in 5.7.0 (#3013, #3014, #3015)

What it adds

A way for a script to move another knowledge base into FreeITSM over the REST API: folders, access lists, pictures inside articles, and creates that are safe to retry without making duplicates. Articles can arrive as drafts with their final company, audience and access list already set, and be published once their pictures and links are in place. How to use it: REST API: Knowledge - Migrating a knowledge base in. How it works inside: Knowledge migration API - Developer Guide.

@Dr4inder sent it as a draft for design review, with a 51-check test of real HTTP requests, concurrent workers and access boundaries. It was merged with their authorship. The rest of this page covers what the review found and what I changed.

How it was reviewed

  1. A separate security read of the whole diff, not anchored on mine, covering company scope, permissions, the image route, the retry table and the screens the PR rewired.
  2. Its tests on a test install, on top of the current code (it was 47 commits behind): 51/51, plus the existing access-list suite 26/26 and the analyst-lifecycle check 21/21.
  3. Every finding checked in the code before anything was changed, and each fix proved with a test that fails on the PR as sent: tests/knowledge-pr378-review-fixes.php fails 6 checks before the fixes and passes 15/15 after.

What held up: the new REST permissions, company scope on every object, the access-list writes (a Knowledge administrator floor on top of the key's permission), the upload path (the shared validator, no SVG, random file names, deny files for Apache and IIS), the image headers, and SQL with every value bound.

1. The editor's save let anyone switch off workflows

What was wrong. The PR taught KnowledgeService::saveArticle() new keys - processing, access, expected_revision, required_image_ids - and gave each its own REST permission. processing: "suppress", for instance, needs knowledge_imports.manage, because it stops the knowledge.published workflow firing. But the editor's own endpoint, api/knowledge/knowledge_save.php, handed the whole request body to that service. Any analyst who could edit an article could send those keys by hand, with no check.

The fix - the endpoint passes on only the keys the screen sends:

$in = array_intersect_key($input, array_flip([
    'id', 'title', 'tags', 'owner_id', 'next_review_date', 'save_as_version',
    'audience', 'folder_id', 'tenant_id',
    'is_published',   // the Publish button on a draft
]));

The lesson. When a shared service learns a new option, every caller that passes input straight through has learned it too. An allow-list at the edge means a new service option is off until a screen deliberately asks for it.

2. One deleted person locked an access list

What was wrong. KnowledgeTransferService::setAccess() checked that every entry on the list named someone who still exists - including entries already stored. The permissions dialog sends the whole list back on every add and remove. So if anyone on a list had since been deleted (the dialog already shows them as "(deleted - safe to remove)"), every change failed: nothing could be added, not even a deny on an open folder, which is the only way to shut someone out of one.

The fix - only a new entry has to exist; a stored one is carried through:

if ($principal && isset($stored[$entry['principal_type'] . ':' . $principal])) {
    $entries[$entry['principal_type'] . ':' . $principal] = [$entry['principal_type'], $principal];
    continue;
}

A new entry naming nobody is still refused: a migration must not silently drop a permission it could not map.

3. Pictures were served to people not signed in

What was wrong. api/knowledge/image.php served a picture with no session at all when its article was published, public and shared with every company. Picture ids count up from 1, so anyone could walk through them. Nothing else in Knowledge serves article content to an anonymous visitor.

Decided (Ed, 19 November 2026): "you should not be able to view content of any sort if you are not authenticated in some way." No session now means 404:

} else {
    // TRAP: nobody signed in = nothing served, not even an image from a
    // public article. ...
    throw new RuntimeException('Unavailable');
}

The PR's own test had a check that anonymous reads worked; it now checks they don't, and that a signed-in portal user still gets the picture.

4. revision was a plain hash over the access list

An article's revision (sent back as expected_revision to avoid overwriting someone's edit) was a plain sha256 over the row - including its access list, which only a Knowledge administrator may read. Any key that could read the article could, in principle, check a guessed list against it. It is impractical, but it was cheap to close: it is now an HMAC keyed from the install's encryption key, the same pattern messaging uses for its media links.

5. Three audit rows for one change

An administrator who is not on an article's list is let in by the administrator floor, and that is recorded as admin_override. One permission edit checks the article three times, so one action wrote three identical rows. It is now one row per article per request.

6. Found on the way: drafts could not be published

Reviewing how the PR stages articles as drafts turned up a gap that was already on main. AI ticket write-ups and project-tool articles are created unpublished on purpose - nothing an AI wrote reaches a requester until a person publishes it - but:

  • nothing on screen marked them: the article endpoint never returned is_published, and a code comment promising "a badge" had no code behind it;
  • nothing anywhere could publish them.

Drafts now carry a Draft badge in the list and under the title, and a Publish button beside Edit. It asks first, then sends only { id, is_published: true } - no body, so it cannot overwrite an edit somebody has open - and fires knowledge.published like any save.

Decided (Ed, 19 November 2026): publishing needs the ordinary edit permission, not a capability of its own - anyone who can edit an article can already create one published.

Also decided: pictures are stored two ways

Pictures pasted into the editor stay inside the article's HTML (#391). Pictures uploaded through the API are stored files with their own table, checked on every view. Decided (Ed, 19 November 2026): keep both. A migration can bring hundreds of large pictures; as data inside the HTML they would ride along with every list, every search index update and every AI call.

πŸ“ Files I changed on top of the PR

File Change
🟑 api/knowledge/knowledge_save.php The allow-list (1)
🟣 includes/services/knowledge_transfer.php Stored entries skip the existence check (2); keyed revision (4)
🟣 api/knowledge/image.php No session, no picture (3)
βšͺ includes/knowledge/visibility.php admin_override once per article per request (5)
🟑 api/knowledge/knowledge_article.php, assets/js/knowledge.js, assets/css/knowledge.css, knowledge/index.php, knowledge/help.php Draft badge and Publish (6)
βšͺ lang/*/knowledge.php Publish strings and the help note, 9 languages
βšͺ api/v1/spec.json The image description no longer promises anonymous reads
🟒 tests/knowledge-pr378-review-fixes.php 15 checks, 6 failing on the PR as sent
🟒 tests/knowledge-migration-api.php Its anonymous check reversed; 52/52

The Publish button was also checked on screen in headless Chrome: a draft shows the badge in the list and on the article, and the button beside Edit.

What is not proven

  • The AI embedding and real workflow delivery after processing: "suppress" were not exercised against a live AI provider (the test install has none); suppression and the reported outcomes were.
  • Older Knowledge visibility tests need the named sample companies and could not run on the test install; they fail the same way on main, so that is not a regression.

Related: REST API: Knowledge Β· Knowledge Β· Knowledge folders and permissions Β· Bugs resolved

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally