Help Assistant

💬 The help assistant

A help icon in the header of every page. Click it, ask how to do something in your own words, and it takes you straight to the part of FreeITSM's help that answers it - in your language.

It works with no AI at all. With nothing set up it searches every help page on your own server: free, instant, and nothing is sent anywhere.

---

Turning it on

The help assistant is off until an administrator turns it on, and then on only for the analysts they choose.

1. Open System → Help assistant.
2. Tick Turn on the help assistant.
3. Under Who has it, tick the analysts who should get it. All and None tick or clear everyone the filter shows - so a team can start with a few people.
4. Save. The first time, FreeITSM reads all its help pages into a help index in the background - a minute or so. Everyone ticked sees the help icon from their next page.

---

Using it

• Ask the way you would ask a colleague - "how do I create a ticketing department?", "what does Enforce approvals do?" - and press Enter.
• The reply is a short line and the help sections that answer it, each with a preview and an Open link that lands on exactly that section. When one section clearly wins it comes first and larger, with a couple of others underneath.
• The conversation follows you. Open a result, move to another module - the window and the conversation are still there. Only Reset clears it, and nobody else ever sees it.
• Drag the window by its header to wherever it is out of the way; it stays there.
• Where you are counts a little. In Workflows, a question that fits several modules leans towards the Workflows help.
• On a phone it opens full screen, and the back button closes it.

It is honest about how sure it is

The line at the top of each reply is chosen by how good the match is:

When	It says something like
One section clearly wins	"This looks like exactly what you need:"
Several are close	"Here's what I found in the help:"
They are from the module you are in	"From the help for the module you're in:"
Nothing matches well	"I couldn't find an exact match, but these might be close:"
Nothing at all	"I couldn't find anything for that - try different words, or name the module you're in?"

It never pretends an AI read anything - it found these sections in the help.

---

What it will show you

• Only modules you can open. Help for a module you do not have never appears, and a module switched off for the install is never searched.
• System help only for administrators, the same as System itself.
• In your language. You are searched and answered from the help in your interface language, with English filling any part not yet translated. The System help pages are in English for now.

How good is it without AI?

Measured on a set of 65 realistic questions:

Asked	A right section in the first five
A plain question	about 9 times in 10
An exact name (Warbot, MoSCoW)	every time
Something vague, sharing no words with the help ("my boss wants a weekly PDF")	about 1 in 3
A language FreeITSM has no help files for	rarely

The last two are what matching by meaning improves.

---

Written answers (optional)

Give the assistant a chat AI and it writes the answer in a sentence or two, in your language, from FreeITSM's own help alone - still linking to the sections it used, so you can check.

1. On System → Help assistant, under Written answers, choose a provider, model and key in the AI panel - any provider FreeITSM supports, including your own model server. A small, fast model is plenty.
2. Tick Write answers with AI.
3. Try it asks a question as you and shows the answer, what the AI was given and how long it took. Nothing is saved.

• It only uses FreeITSM's help - it is told never to invent a menu or button, and to write menu names exactly as they appear on your screen.
• When the help does not cover something, it says so, shows the closest sections, and the question joins Unanswered questions.
• It respects permissions - asked about a setting you cannot change, it tells you who can.
• Measured: 46 of 47 plain questions and every exact feature name answered from the right section, in about three seconds and a third of a penny each (Claude Haiku).
• Its own key, stored encrypted. Each question and the help found for it go to that provider - choose your own model server to keep everything on your network.
• It never makes things worse - if the AI cannot be reached, you get the search results instead.

---

Unanswered questions

Writing the missing help? Good vs bad help for the assistant.

When the assistant cannot answer a question - nothing found, or only weak matches - it keeps it on System → Help assistant → Unanswered questions, in the words the person used. It is the best list there is of help worth writing.

• Administrators get a bell notification - one entry with a count, however many come in. The person who asked never does.
• It is only kept when the help is really missing. A question the help answers in a module the asker cannot open is not kept.
• Done marks a question handled once the help covers it; Reopen puts it back.
• Names are not kept by default. To follow up with someone, tick Record who asked beside them under Who has it - their name is then kept with their unanswered questions, and their window tells them so.

---

Matching by meaning (optional)

Word search finds help that uses the same words as your question. Give the assistant an embedding model and it also understands what you mean - so "my boss wants a weekly PDF of how we are doing" finds Report packs.

1. On System → Help assistant, under Matching by meaning, tick Match questions by meaning.
2. Choose OpenAI, Azure OpenAI or your own model server (Ollama, LM Studio...), enter its key or address, and pick the model from the list. Test checks it works.
3. Save. The help's vectors are built in the background. With OpenAI's text-embedding-3-small they come ready-made with each release, so only sections changed on your install are paid for.

On the same 65 test questions, loosely worded ones went from 2 in 6 answered to 6 in 6, and plain ones from 43 to 46 of 47.

• Its own key, stored encrypted, so its cost shows on its own. Building costs about a penny on OpenAI; each question a tiny fraction of that.
• Each question goes to that provider. Choose your own model server to keep everything on your network.
• Changing the model needs new vectors - vectors from different models cannot be compared. The page warns you and offers Rebuild; the old model keeps answering until the new vectors are ready.
• It never makes things worse - if the provider cannot be reached, the assistant searches by words, as it does with nothing set up.

---

The help index

So it can answer instantly, the assistant keeps a copy of every help page ready to search, in English and every language your analysts have chosen. It is only a copy - rebuilding it never loses anything.

• It is built for you the first time you save with the assistant on.
• Rebuild after an upgrade - System → Help assistant tells you when the help has changed since the index was built.
• Rebuild when an analyst picks a language nobody used before.
• A rebuild runs in the background - about half a minute per language. You can leave the page.

---

What is coming

The same window, getting better as you give it more - and never worse without it.

Set up	What it adds
Nothing (today)	The right help sections, instantly and free
An embedding key (available now)	Matching by meaning, so loosely worded questions find their answer - see above
A chat AI (available now)	A written answer in a sentence or two, in the asker's own language, still linking to the help it used - see above

---

Related

• The help assistant - design - the plan, the decisions and why
• The help assistant - Developer Guide - how it works under the hood