Portal Help Centre

Portal Help Centre

Where: the self-service portal → Knowledge Publish with: Knowledge → tick articles → Set who can see them Starts empty on purpose — every article begins as analysts only

Your customers can read your knowledge base in the self-service portal. Articles reach them three ways, in rising order of how hard the customer has to look:

Where	When they see it
Dashboard → Popular articles	Straight away, without looking. The six most-read articles published to customers
Knowledge (the nav)	When they go looking — searchable list
Under the subject box	While typing a new ticket, if the subject matches — ticket deflection

All three ask the same question of the database (see Under the hood), so none of them can surface something the others wouldn't.

Getting the first articles in front of people

Nothing appears until you publish something, and that isn't a bug. Every article starts as Analysts only, so that adding the visibility feature could never quietly expose anything you hadn't chosen to share. A brand-new portal Knowledge section is therefore an empty one.

To fill it:

1. Go to Knowledge.
2. Tick the articles you want customers to read (there's a Select all if you're publishing everything).
3. Choose Analysts and signed-in customers and click Apply.

Your selection survives searching and tag filtering, so you can work through everything about VPN, then everything about printers, and apply once at the end.

💡 Read a few of them as a customer would first. Articles written for analysts often assume access to systems the customer doesn't have, or contain internal hostnames. Publishing is one click; unpublishing after someone has read it is not.

Who can see what

Three levels, each including the ones more open than it:

Level	Analysts	Signed-in customers	Anonymous web chat
Analysts only (default)	✅	—	—
Analysts and signed-in customers	✅	✅	—
Anyone, including website chat	✅	✅	✅

The portal reads at the middle level, so it shows articles marked for customers and those marked public.

Never shown, whatever the level:

• Unpublished articles
• Deleted articles (in the recycle bin) — note that deleting an article does not unpublish it, so both are checked
• On a multi-company system, another company's articles. Customers see their own company's articles plus anything shared with all companies

Ticket deflection

When someone starts typing the subject of a new ticket, matching articles appear underneath the box.

It's deliberately quiet:

• Nothing appears unless there's a genuine match
• It waits until they've typed at least three characters, and pauses while they're still typing
• It never blocks or interrupts submitting a ticket
• Nothing about what was typed is recorded anywhere

It searches exactly the same articles the Knowledge page does, so it can't surface anything Knowledge itself wouldn't show.

Why it's worth publishing more than you think. Deflection only works on articles a customer is allowed to see. An excellent VPN guide marked analysts only deflects nothing.

Popular articles on the dashboard

The dashboard shows the six most-read articles you've published to customers, so the answer to "how do I reset my password?" is on screen before anyone goes looking — or raises a ticket about it.

• Ordered by how often each article has actually been read (knowledge_articles.view_count), not by anything anyone assumed. The list reflects what your customers keep needing
• The counter is the same one the analyst side increments — a read is a read, wherever it happened
• Clicking one opens it in the ordinary Knowledge reader; there is no second article viewer to keep in step
• It loads separately from the rest of the dashboard, so a slow knowledge base can't delay the tickets the page is really for
• Publish nothing and the section simply says so, rather than sitting empty

💡 Because it's ordered by reads, it's self-correcting: publish twenty articles and within a few weeks the dashboard is showing the handful people genuinely land on. It's also a decent signal for what to write next — an article climbing the list is a question your desk is answering a lot.

Worked example

Sarah works at Northwind, which is one of several companies on your system. She goes to raise a ticket and types "vpn keeps dropping".

As she types, two articles appear beneath the subject box:

• How to connect to the VPN — shared with all companies, marked customers
• Northwind VPN split-tunnel settings — belongs to Northwind, marked customers

She does not see:

• VPN troubleshooting runbook — marked analysts only
• Contoso VPN configuration — belongs to a different company
• Old VPN guide (superseded) — in the recycle bin

She opens the first, follows it, and closes the tab without raising a ticket. Nothing is logged about her search.

What customers can't do

• They can't reach an article by guessing its address. Visibility is decided in the database query, not by hiding links, so an article they're not allowed to see returns the same "not available" as one that doesn't exist — it never confirms the article is real.
• They can't ask for a different visibility level. The portal always reads as "signed-in customer" — that isn't something the browser can ask to change.
• They can't change the sort into something else. The dashboard asks for sort=popular; anything else falls back to alphabetical. It's a fixed list of two, not a field passed to the database.
• They can't see which company an article belongs to, only whether they can read it.

Notes

• The portal section is called Knowledge — matching what it's called everywhere else in FreeITSM — and the portal's own guide is simply Help, so there aren't two things with the same name.
• Article content is written in the normal knowledge editor. Formatting, links, images and tables all carry through; anything active is stripped before display, since an article is being shown in a customer's session.
• Articles are deep-linkable — help-centre.php?id=12 opens one directly, so you can paste a link into a ticket reply.

Under the hood

Colour key: 🖥️ page/UI · 🔌 API · ⚙️ shared logic · 🎨 assets · 🗄️ storage

🎨	File	Role
🖥️	self-service/help-centre.php	The Knowledge page — search, list, article view, deep links (?id=)
🔌	api/self-service/get_knowledge_articles.php	List + search + sort=popular, scoped. Powers all three surfaces
🔌	api/self-service/get_knowledge_article.php	One article, scoped. Bumps view_count
⚙️	includes/knowledge/portal_reader.php	🔑 The scope itself — portalKnowledgeScope(), portalUserTenantId(), portalArticlePreview()
🖥️	self-service/index.php	The dashboard's popular articles section
🖥️	self-service/new-ticket.php	The deflection suggestions under the subject box
🔌	api/knowledge/knowledge_bulk_audience.php	The bulk "who can see them" action
🖥️	knowledge/index.php + assets/js/knowledge.js	Article ticks, the bulk bar, the audience picker
⚙️	includes/knowledge/audience.php	The three levels and the SQL filter
⚙️	includes/tenancy.php	knowledgeTenantFilterForCompany() — company scoping
⚙️	includes/services/knowledge.php	saveArticle() — the bulk action loops over it
🎨	assets/js/safe-html.js	Cleans article HTML before it reaches a customer's session
🗄️	knowledge_articles.audience	internal | customer | public, defaulting to internal
🗄️	knowledge_articles.view_count	Reads, from both the portal and the analyst side — orders the popular list

One question, asked in one place. Every surface above calls portalKnowledgeScope(), which returns the WHERE fragment for "articles this requester may read". That used to be copy-pasted per endpoint, and duplicated scope is the dangerous kind: nothing breaks when the copies drift, one of them just quietly starts showing more than it should.

Two details worth knowing if you're reading it: the audience is hard-coded to customer inside that function rather than accepted from the request, and knowledge uses a different company rule from tickets — a blank company on an article means shared with everyone, the opposite of a blank company on a ticket.

The bulk "who can see them" action is a thin loop over KnowledgeService::saveArticle(), which updates audience only when that key is present, rejects an invalid audience outright rather than normalising it down to internal, and refuses articles belonging to a company the analyst can't reach — a hand-rolled UPDATE would have bypassed all three. Partial success is reported, never swallowed: silently skipping three articles of fifty is how someone believes a document is published when it isn't. (The tick selection survives searching and tag filtering because it lives in JavaScript, not the DOM.)

portalArticlePreview() builds the list snippets: it drops <script>/<style> blocks whole — strip_tags alone keeps a tag's contents — and inserts a separator before each tag so a heading doesn't run into the sentence after it.

See also

• Knowledge — writing and managing articles
• Self-Service Portal — the portal itself
• Portal privacy — what customers see of their own tickets