Knowledge articles
Overview
Knowledge articles are the organisation's wiki — handbooks, instructions, curated experience. They live in knowledge spaces, carry a version and a status.
What distinguishes this wiki from a folder full of files is the review interval: an article reports itself when it has gone unchecked for too long. Without that, every knowledge collection rots — not because it was set up wrongly, but because nobody notices when it has grown old.
Core tasks
Write an article. New article requires title, space, summary and body. The list shows title, space, status, review, version and last change; filtering is by space and status.
Keep versions. On saving you choose between a draft and a new version with a version comment. Versions can be compared; if two are identical in content, the display says so explicitly rather than showing an empty comparison. The comparison works per block — heading, paragraph, list, table, quote, code: each block appears as New, Removed or Changed, a changed one with Before and After side by side. Show the unchanged blocks when you need the context.
Publish. An article is published deliberately — drafts stay internal.
Plan maintenance. An article carries an author, a review interval in days and the time of the last check. Once the interval has passed, review due appears.
Release to the portal. The In portal switch makes an article visible to customers — a separate decision per article, not a consequence of publishing.
Set favourites. Frequently used articles can be marked as favourites.
Arrange in the tree. View → Tree shows the outline of a space: sub-articles sit below their parent. With the edit permission and contribute access to the space, you drag an article by its handle to another position or below another article. Without a mouse it works the same: focus the handle, then ↑/↓ moves among siblings, → nests the article under the previous one, ← moves it one level up. When creating or editing, you pick the Parent article directly; new articles land at the end of their level. An article cannot be placed below itself or one of its own sub-articles.
Browse the handbook. In a space of type Handbook, every article shows the handbook outline, the path to it above (breadcrumbs) and Previous and Next in reading order below — an onboarding can be read from start to finish.
Link internally. The link button in the editor opens an article picker: search, pick, done. Without selected text, the title becomes the link text. A free address remains possible; an existing link can also be removed there. Clicking an internal link in an article opens the target article without reloading the page.
Table of contents. If an article has at least two headings, the right column shows Contents with all headings of levels 1 to 3. A click jumps to the place in the text.
Autosave. For drafts, the editor saves the text by itself after a short pause in typing — as an intermediate state without a new version; below the editor you see when it was last saved. For published articles the editor does not save in between: your changes take effect only when you click Save, so readers never see a half-finished state; a note below the editor says so. If someone else has saved the article in the meantime, autosave stops and says so instead of overwriting their changes; secure your text and reload the article. A version is still created with Save as new version.
Writing in the block editor. You edit articles in the same block editor as pages: headings, lists, checklists, tables (button Insert table), dividers, quotes, code, images and videos are blocks of their own. What is stored are the blocks; the reading version (HTML) for the article, the portal and search is derived from them. Existing articles were converted into blocks once during the update — text, links, images, tables and lists are kept.
Writing a draft together. If co-editing is set up for you, several people write the same draft at the same time — just like pages: you see the others' cursors with their names, and Live appears below the editor. During co-editing every change is saved for everyone right away; Save then takes over title, excerpt and placement and, if you want, creates a version from the shared state. If the connection drops, the editor continues with your latest state and saves as usual again. You always edit published articles on your own — changes reach readers only when you click Save.
Mention people. With @ in the editor you pick a person from the team. They receive a notification with a link to the article — provided they may read the space (for drafts only those who may see drafts). People already mentioned are not notified again on the next save.
Embed content. Above the editor you find Image, Video and File. Image inserts an image (PNG, JPEG, GIF, WebP up to 1.5 MB) directly into the text. Video takes an address from YouTube or Vimeo (for example https://www.youtube.com/watch?v=…, https://youtu.be/…, https://vimeo.com/…) or the https address of a video file (MP4, WebM, Ogg). When reading, videos from YouTube and Vimeo first appear as an area with the button Load video: only after this click does the browser load anything from the provider (privacy), YouTube in its privacy-enhanced mode. Other providers and any other embedded third-party pages (iframes) are not allowed for security reasons. File uploads a file as an attachment of the article and puts a link to it into the text; a click on the link downloads it.
Complete a review. Once review due is set, the author receives a notification — if the article has none, the owner of the space and the managers entered by name do. A manager grant for a role does not notify anyone. After checking, Mark as reviewed records the time of the last review and starts the next interval; only then does the next reminder come.
Summarize and translate with AI. If AI is switched on, the article carries the buttons Summarize and Translate. Summarize suggests two to three sentences; only Use as excerpt saves them as the article's excerpt. Translate asks for the target language and creates the translation as a new draft in the same space — headings, lists and links are kept, the draft is linked to the original and opens for review. This requires the permission to create articles and contribute access to the space. If AI is switched off, both buttons are missing.
Link knowledge to a record. On the page of a customer, project, ticket or task, the Linked knowledge card shows the articles, SOPs, templates and solution blocks linked there. With the knowledge.link.manage permission you link further knowledge or remove a link there.
Matching knowledge suggested. On projects, tickets and tasks the card shows Might be relevant below the links: articles and SOPs whose title or text contains the keywords from the title (and tags) of the record — best first, at most five. Only what you may read and what is not linked yet is suggested. Link takes over a suggestion with one click.
Capture lessons learned. Once a project is completed, its header offers Capture lessons learned. You choose a space you may write to and optionally a document template as a skeleton ({{projekt}} and {{kunde}} are filled); without a template the draft gets the outline Goal and outcome, What went well, What did not go well, What we will do differently. The article is created as a draft, is linked to the project right away and opens for writing. There is one such article per project — afterwards the button reads Open lessons learned.
Fields in detail
The What it does column answers what changes in the system — not what the field is called. The grey name behind the label is the API field: the same thing runs under that name through automation, import and AI tools.
Creating and editing an article
| Field | Required | Values / format | What it does |
|---|---|---|---|
Title title | yes | text, max. 255 characters | The heading. Appears in list, search, assistant citation and in the portal. |
Address slug | no | text, max. 255 characters | The readable part of the address. Built from the title; changed by hand, existing links to the article break. |
Space spaceUlid | yes | an existing knowledge space | Where the article lives. The space decides visibility and access — not the article itself. |
Parent article parentUlid | no | an existing article | Makes the article a sub-entry. This is how the structure of a handbook arises. |
Status status | no | draft, review, published, archived | Where the article stands. Only published is visible to others and cited by the assistant; review is the intermediate step for four-eyes approval. |
Excerpt excerpt | no | text, max. 500 characters | The teaser in result lists and tiles. Without it the system takes the first sentences — which rarely fits as well as a written one. |
Content (blocks) blocks | no | block list as for pages | The article as it is stored. The reading version bodyHtml and the search text bodyText are derived from it. Takes precedence over bodyHtml. |
Body bodyHtml | no | formatted text | Reading version of the article. When writing through the API, the HTML is cleaned and converted into blocks — images, tables, checklists and file attachments are allowed. |
Tags tags | no | several terms | Classification across space and structure; drives search and suggestions. |
Order sortOrder | no | number | Position among siblings in the structure. |
Review interval (days) reviewIntervalDays | no | 0 or more | After how many days the article is flagged for review. 0 means never. This is the field that protects knowledge from ageing unnoticed. |
Publish to portal publishedToPortal | no | yes/no | Makes the article visible to customers in the portal. Bear in mind that internal phrasing then goes outside too — this switch is not the same as "published". |
Versions
| Field | Values / format | What it does |
|---|---|---|
Save version saveVersion | yes/no | Creates a new version on saving instead of overwriting the existing one. Only then can you compare and roll back later. |
Edit summary editSummary | text, max. 255 characters | What changed. It appears in the version list — the sentence that explains why, six months on. |
Version versionNo | number | Which saved version to roll back to. |
Editing state baseUpdatedAt | point in time (ISO 8601) | The state the editor works on; autosave sends it by itself. If someone else has saved in the meantime, nothing is overwritten — the response reports a conflict. |
Moving in the tree
| Field | Values / format | What it does |
|---|---|---|
Parent article parentUlid | article of the same space, empty = top level | Which article the move nests under. |
Position position | number from 0 | Where among the siblings the article lands; the others move along. Without it, the article goes to the end. |
Settings & permissions
- Module
module.knowledge. knowledge.article.view,.create,.edit,.deleteand — deliberately separate
— knowledge.article.publish. Writing and publishing are two different authorities.
knowledge.brand.allfor spaces across every brand — only takes effect when the permission is granted for all brands. Drafts in a brand-bound space are editable only with the edit permission in that brand.- Visibility hangs off the space. An article inherits the access of its
knowledge space; the portal release comes on top of that.
FAQ & troubleshooting
A customer cannot see an article. Two conditions have to coincide: published and released in portal. Each is its own decision.
I can write but not publish. Then knowledge.article.publish is missing.
"Review due" does not go away. The notice ends with Mark as reviewed — saving alone does not reset the timestamp.
Moving in the tree is rejected. Either contribute access to the space is missing, or the target would be a cycle (the article below itself or one of its own sub-articles).
The version comparison shows nothing. Then the chosen versions are identical in content. The display says so explicitly.