ITSM

Knowledge Base

Article fields, states, versioning, access control, semantic search, and portal surfacing for the Knowledge Base module.

Overview

The FlowOS Knowledge Base stores how-to guides, troubleshooting articles, known error workarounds, and process documentation. Articles appear in the self-service portal, are surfaced by the virtual agent, and are linked from ITSM records. Full-text and semantic vector search power the search experience.

Article Fields

Field	Type	Required	Default	Description
number	string	optional	—	Human-readable identifier, e.g. "KB-0042". Auto-generated.
title	string	required	—	Article title.
slug	string	required	—	URL slug, unique per tenant. Looked up via GET /api/knowledge/slug/:slug.
category	string	required	—	Category label. The values "Known Error", "KEDB" and "known-error" are also matched by the KEDB endpoint (see isKEDB below).
knowledgeBaseId	ObjectId	optional	—	Optional grouping into a specific knowledge base.
knowledgeBaseTitle	string	optional	"General Knowledge"	Denormalized display name of the knowledge base.
excerpt	string	optional	""	Short summary shown in listings.
body	string	optional	""	Full article content.
tags	string[]	optional	[]	Free-form tags.
isPublished	boolean	optional	false	The default (unfiltered) list request only returns isPublished: true articles — pass allStates=true, manage=true, or an explicit isPublished/state filter to see the rest.
state	enum	optional	"draft"	"draft" · "review" · "in_review" · "approved" · "published" · "retired" · "rejected". The broad lifecycle field — see Article Lifecycle below.
reviewStatus	enum	optional	"draft"	A second, narrower field tracking the approval workflow specifically — see Approval Workflow below.
confidentialityLevel	enum	optional	"internal"	"public" · "internal" · "restricted"
isKEDB	boolean	optional	false	Marks this as a Known Error DB article, surfaced by GET /api/knowledge/kedb.
workaroundSteps	string	optional	—	Workaround text for a known-error article.
authorId / authorName	ObjectId / string	optional	—	Set from the creating user. authorName defaults to "System".
ownerId / ownerName	ObjectId / string	optional	—	Defaults to ownerName "IT Knowledge Team".
contributors	string[]	optional	[]	Additional contributor identifiers.
version	integer	optional	1	Current version number — see Version History below.
relatedIncidentIds	ObjectId[]	optional	[]	Incidents this article is linked to.
linkedProblemId	ObjectId	optional	—	Problem this article documents a workaround for.
incidentsResolvedUsing	number	optional	0	Counter for incidents resolved with this article’s help.
views / viewCount	number	optional	0	Two separate view counters, both present on the schema.
deflectionCount	number	optional	0	Incremented by POST /:id/deflect (viewed the article instead of filing a ticket).
helpful / notHelpful	number	optional	0	Feedback tallies from POST /:id/feedback and /:id/rate.
publishedAt	Date	optional	—	Set by POST /:id/publish.
expiresAt	Date	optional	—	Indexed; read by the background knowledge-expiry worker.
attachments	object[]	optional	[]	{ filename, url, size, mimeType, uploadedAt }[]
feedback	object[]	optional	[]	{ userId?, userName?, helpful, comment?, createdAt }[] — one entry per feedback/rate submission.

Article Lifecycle

Articles carry two lifecycle-shaped fields on the same document: the broad state field (draft · review · in_review · approved · published · retired · rejected) and the narrower reviewStatus field used by the Approval Workflow actions below. The two lifecycle actions on this page set both together:

Field	Type	Required	Default	Description
POST /:id/publish	action	optional	—	Sets state: "published", reviewStatus: "approved", isPublished: true, publishedAt: now.
POST /:id/retire	action	optional	—	Sets state: "retired", reviewStatus: "retired", isPublished: false.
POST /:id/archive	action	optional	—	Same effect as retire — sets state and reviewStatus to "retired".

There is no scheduled job that auto-transitions an article when expiresAt passes — the field is indexed and read by the knowledge-expiry worker, which is a notification/flagging pass rather than an automatic state change.

Search & Listing

There is no dedicated semantic or full-text search endpoint. Search is a query parameter on the regular list endpoint: GET /api/knowledge?q=... (aliases: search, $search) runs a case-insensitive regex match across number, title, excerpt, body, tags and category — not a ranked BM25 or vector-similarity search. Combine it with any of the filters below.

bash

GET /api/knowledge?q=vpn+password&category=Networking&isKEDB=false&tag=remote-access&knowledgeBaseId=665f...

// Response
{
  "articles": [
    {
      "_id": "665f1a2b3c4d5e6f7a8b9c0d",
      "number": "KB-0042",
      "title": "Reset VPN Credentials (GlobalProtect & OpenVPN)",
      "excerpt": "Steps to reset your VPN password and re-authenticate...",
      "category": "Networking",
      "tags": ["vpn", "remote-access"],
      "isPublished": true,
      "state": "published"
    }
  ],
  "records": [ /* same array */ ],
  "total": 1
}

The plain GET /api/knowledge list (no explicit state, allStates, manage or isPublished query param) implicitly filters to isPublished: true — pass manage=true from an authenticated admin view to see drafts and unpublished articles too.

Version History

Every article stores its own revision history inline, as a versions[] array on the article document — there is no separate versions collection. A new entry is appended (and the article's version counter incremented) whenever content is saved through updateArticleWithVersion, such as when restoring a prior revision.

Field	Type	Required	Default	Description
version	integer	required		Sequential version number for this snapshot.
content	text	optional	""	Snapshot of the article's body at the time this version was recorded.
title	string	optional	""	Snapshot of the article title at the time this version was recorded.
editedBy	string (usr_...)	optional	null	User who made this edit.
editedAt	timestamp	optional	now	When this version was recorded.
changeNote	string	optional	null	Optional note describing the change, e.g. "Restored from version 3".

GET

/api/knowledge/:id/versions

List version history, newest first

GET

/api/knowledge/:id/versions/:versionId

Get a specific version's content

POST

/api/knowledge/:id/versions/:versionId/restore

Restore the article's title/body from a prior version, recording a new version entry with the note 'Restored from version :versionId'

Approval Workflow

Articles carry a dedicated reviewStatus field, separate from the broader lifecycle state field, to track approval specifically: draft → in_review → approved | rejected → published / retired.

Field	Type	Required	Default	Description
reviewStatus	enum	required	draft	draft · in_review · approved · rejected · published · retired. Tracks the approval workflow independently of the lifecycle state.
reviewedBy	string (usr_...)	optional	null	User who approved or rejected the article.
reviewNote	string	optional	null	Reviewer note, typically populated on rejection.
submittedForReviewAt	timestamp	optional	null	Set when the article is submitted for review.
approvedAt	timestamp	optional	null	Set when the article is approved.

POST

/api/knowledge/:id/submit-for-review

Move the article to reviewStatus=in_review and notify KB approvers/managers

POST

/api/knowledge/:id/approve

Approve the article (reviewStatus=approved), publish it, and notify the author

POST

/api/knowledge/:id/reject

Reject the article (reviewStatus=rejected) with an optional reviewNote, and notify the author

Reviewer notification

Submitting an article for review creates an in-app notification (linking back to the article) for every user holding a KB manager/approver role — kb_approver, knowledge_manager, kb_manager, knowledge_admin, itil_admin, or admin. Approving or rejecting likewise notifies the article's author.

Comments

Articles support a lightweight discussion thread, stored as a separate KbComment collection (root_kb_comments) keyed by articleId.

Field	Type	Required	Default	Description
articleId	string (kb_...)	required		The article this comment belongs to.
authorId	string (usr_...)	required		User who posted the comment.
body	string	required		Comment text.
createdAt	timestamp	optional	auto	Creation timestamp.

GET

/api/knowledge/:id/comments

List comments on an article, oldest first

POST

/api/knowledge/:id/comments

Add a comment (body is required)

DELETE

/api/knowledge/:id/comments/:commentId

Delete a comment — only the comment's own author may delete it (403 otherwise)

API Quick Reference

GET

/api/knowledge

List articles

POST

/api/knowledge

Create an article

GET

/api/knowledge/:id

Get article with full content

PATCH

/api/knowledge/:id

Update article

DELETE

/api/knowledge/:id

Delete article

POST

/api/knowledge/:id/publish

Publish article

POST

/api/knowledge/:id/retire

Retire article

POST

/api/knowledge/:id/archive

Archive article (sets state and reviewStatus to retired)

POST

/api/knowledge/:id/feedback

Submit helpful/not helpful feedback with an optional comment

POST

/api/knowledge/:id/rate

Public: rate an article helpful/not helpful

POST

/api/knowledge/:id/view

Public: track an article view

POST

/api/knowledge/:id/deflect

Public: track a deflection (viewed article, did not file a ticket)

GET

/api/knowledge/:id/versions

List version history

POST

/api/knowledge/:id/submit-for-review

Submit for approval review

POST

/api/knowledge/:id/approve

Approve and publish

POST

/api/knowledge/:id/reject

Reject with a review note

GET

/api/knowledge/:id/comments

List comments

POST

/api/knowledge/:id/comments

Add a comment

GET

/api/knowledge/analytics

Knowledge deflection analytics

GET

/api/knowledge/kedb

List Known Error DB articles (isKEDB or KEDB/known-error category)

GET

/api/knowledge/gap-analysis

Resolved incidents with no matching published KB article, grouped by category

POST

/api/knowledge/from-incident

Create a draft article from an incident