Knowledge

Knowledge holds articles: how to fix what comes up again and again, procedures, and answers for customers. Articles live in knowledge bases, and each knowledge base has one audience: staff, customers on the portals, or only some accounts. Articles are written as drafts, reviewed when the knowledge base asks for it, and published in versions, so readers always see a finished article while the next one is written.

Knowledge comes with the Knowledge plugin. If you don't see Knowledge under Customer Service in the sidebar, the plugin is off; an admin turns it on under Platform → Plugins.

Who can use it

Who	Can
Agent	Read articles, write them and edit drafts, and submit them for review.
Knowledge Manager	Everything: also publish, send back and retire articles in any knowledge base, and set up knowledge bases.
Viewer, Auditor	Read published articles.
Knowledge Manager, Analyst, Auditor	The Knowledge dashboard.
A knowledge base's owners and reviewers	Publish, send back and retire its articles; owners also look after its categories.
Platform Administrator, Organization Administrator	Everything.

You read a knowledge base when you have knowledge.read in its organization and you are in its audience: for a staff knowledge base limited to some units, you work in one of them, below one, or above one. Every member of staff who reads knowledge sees the knowledge bases for customers and accounts too, so they can send links. People who write articles see drafts; everyone else sees only published articles.

Knowledge bases

Open Knowledge, then Knowledge bases (with knowledge.settings). Each knowledge base has:

• Who reads it, exactly one of:
  • Staff: everyone in the organization, or only staff in the units picked (and the units below them).
  • Customers: contacts on the portals picked (none picked: every portal), signed in or, with Readable without signing in, anyone with the portal's address.
  • Some accounts: only signed-in contacts of the accounts picked, on their portals. For a customer's own procedures, or a pilot.
• Owners: publish its articles, look after its categories, and get its articles when their review is due.
• Reviewers: when any are set, every version is reviewed: it is published by a reviewer or a Knowledge Manager, never by the person who wrote it.
• Categories: one level of folders, in the order you set. Deleting a category leaves its articles without one.
• Archived: hidden from the lists, and no new articles; its articles stay readable.

An article never has an audience of its own: to change who reads it, move it to another knowledge base. Changing a knowledge base's audience, and moving an article, are kept in the audit log with before and after. Moving a published article needs the right to publish in both knowledge bases; when the one it moves to has reviewers, someone other than its author or whoever sent it for review moves it.

A knowledge base with articles can't be deleted; archive it instead.

The Knowledge page

The list shows the articles you read, recently changed first: the title with the key (KB-1, KB-2 … per organization) and summary, the knowledge base, the category, the state, the owner and when it was changed. Columns adds the audience, when it was published, the review date and the views.

• Search finds words in the title, the summary, the keywords and the published text, or a key like KB-12.
• Filters: Knowledge base, its Category, and State (current articles by default: not retired).
• At a glance: articles In review, those whose Review due date has passed, those with a New version waiting, and Mine (that you own).

The number next to Knowledge in the sidebar is how many articles wait for review.

Writing an article

New article opens the editor: the title, a one-line summary, the text in Markdown (with a Preview), the knowledge base and category, the owner (you, unless you pick someone), keywords people search for, and, with their plugins on, the services and configuration items it is about. Save draft saves version 1.

State	Means
Draft	Being written; not published yet.
In review	Waiting for a reviewer to publish it or send it back.
Published	Readers see it.
Retired	No longer shown to readers; kept with its versions.

Editing a published article makes a new version, a draft: readers keep seeing the published version until the new one is published. The article shows v2 draft in the list, and the page says which version you see. Every save goes to that same draft until it is published. Discard the draft (under …) throws it away.

Review and publishing

• Without reviewers, a Knowledge Manager or an owner publishes the draft with Publish.
• With reviewers, the writer clicks Submit for review. A reviewer reads it and either clicks Publish, or Send back… with what to change; the writer sees the comment on the article. Changing a version in review sends it back to draft, so what the reviewer saw is what gets published.

Publishing sets the article's Review by date a year ahead. When it passes, the article shows it, and Mark reviewed (under …) says it is still right for another year; or edit it.

Retire… takes an article away from readers, with a reason, and Restore brings it back. A draft that was never published is deleted instead (Delete the draft). Each version is kept with who wrote it, who reviewed and published it, and when; the Versions list on the article opens any of them.

On the portal

A portal with customer knowledge has a Knowledge page in its menu. A contact sees the knowledge bases they read there: Customers ones readable without signing in to everyone, the other Customers ones once signed in, and Some accounts ones only when they are signed in as a contact of one of those accounts. Staff knowledge bases never show on a portal. Signed out, the page says when there is more to read after signing in.

The page lists the published articles, most read first, by knowledge base and category, with a search box that looks for the words in the title, summary, keywords and text. An article shows its published version, other articles in its category, and a link back to send a request.

• Was this helpful? under every article: Yes, or No with what was missing.
• While typing a request: beside a portal form, articles matching what the contact has typed so far show up. That solved it counts as a request not made (a deflection).

Opening an article counts a view, once a day per visitor. Feedback and deflections are kept per article and version; a visitor can give feedback on an article three times a day.

On cases and incidents

A case's side panel and an incident's show Knowledge: published articles you read that match the case's subject and request, or the incident's title, those about the incident's service or configuration item first. Articles from customer knowledge bases have Copy link: the article's address on the portal, to paste in a reply. An article's own page shows the same address.

Writing from a case or a known error

On a case, the Knowledge panel has Write an article: a new article starts with the case's subject as its title and the request as the question, for you to write the answer. On a problem with a workaround, Write an article in its menu starts one from the known error: what happens, why, and the workaround (the text for customers, when there is one), about the problem's service and configuration items. Either way the version's note says where it came from (Written from CASE-1042), and the article goes through review and publishing as any other.

For managers and auditors

The Knowledge dashboard shows articles waiting for review and past their review date, and over a period what was published, what readers said and what solved requests on the portals. Published articles are evidence for auditors: each version published in a period, with who wrote, reviewed and published it.

The API and assistants

The Knowledge API is described in the Knowledge plugin's API. Assistants connected over MCP search and read articles the person may read, and write drafts; publishing follows the same review as in the app.