Searching Inside Tickets

Searching inside tickets

The ticket search used to answer one question: which ticket is this? You gave it a reference, an address or a subject, and it found the ticket.

It now answers a second, harder one: which tickets mention this? — looking inside every message and every note, not just the subject line. A phrase buried in the fourth reply of a two-year-old ticket is findable.

---

Where it is

Open the search icon above the ticket list. The window has a new field:

Anywhere in the ticket — words from a message, a note, or a subject

Type into that box and press Enter. The three fields above it are unchanged and still do exactly what they did before, so nothing you already rely on has moved.

If you fill in both, the content search wins — it is the more specific thing you asked for.

---

What a result looks like

Each result shows the ticket reference and subject as before, plus two new things:

• a snippet — the text around your match, so you can tell whether it is the ticket you wanted without opening it
• where it was found — subject, message or note, and how many other places in that ticket also matched

A ticket appears once, however many of its messages match. Without that, one long thread that mentions your word ten times would fill the entire first page.

---

How to search well

Type this	And you get
printer jam	Tickets containing both words, anywhere, in any order
"printer jam"	Only that exact phrase, those words in that order
printer -jam	Messages with printer but not jam

Three things are worth knowing, because they explain results that would otherwise look wrong.

Word order never matters (unless you use quotes). Searching tower london finds "Tower of London".

Plurals are not automatic, but mostly work anyway. The database treats printer and printers as unrelated words. FreeITSM softens this by matching word beginnings, so printer does find printers — but printers will not find printer. If a search comes back thin, try the shorter form of the word.

Spelling has to be right. There is no "did you mean". A single transposed letter finds nothing.

Very short words

Databases do not remember very short words — usually anything under three letters. If you search for one, FreeITSM tells you rather than pretending nothing matched, because an empty page would read as "that is not in your tickets", which would not be true.

---

What it does not search yet

Attachments. The text inside an attached PDF, Word document or spreadsheet is not searched. Filenames are not searched either. That is a separate and considerably harder piece of work — reading text out of arbitrary documents — and it is not built.

Text inside attachments. A PDF or a Word document attached to a ticket is not searched — only the message and note text. That is the next substantial piece of work.

---

Setting it up

Two steps, both genuinely one-off.

1. Create the index. Open System → Database Verification and run it. That creates the table the search uses.

2. Fill it with the tickets you already have. From a command line in the FreeITSM folder:

php scripts/search_backfill.php

It reads every ticket subject, message and note already in your database and makes them searchable. On a small installation this takes seconds. It is safe to run again at any time — re-running updates what is there rather than duplicating it.

From then on it looks after itself. New tickets, replies and notes are indexed as they happen, whether they arrive from an analyst, the self-service portal or by email, and a ticket you send to the trash drops out of the search immediately. You do not need to run anything on a schedule.

Checking on it later: System → Search

System → Search shows what the index holds: how many entries, how many of your tickets and articles are in it, when it last changed, and whether anything is missing. There is a Rebuild index button there too, so you never need a command line again — useful on hosting that does not give you one.

It rebuilds in slices with a progress bar, so a large installation cannot time out halfway through.

When you might rebuild

• After correcting the full-text settings (see the word-length warning below) — words that were skipped before need re-reading
• If the Search screen says some tickets or articles are not in the index
• After restoring a database from a backup taken before the index existed

The screen also tells you the shortest word your database will search for. That single number explains most cases of "search finds nothing".

---

If a search finds nothing you expected

Run System → Debug Tools → D007 — Search corpus health. It takes about a second and ends in a plain-English verdict.

It is worth running once when you first set this up, not only when something looks wrong. The reason is that database search fails quietly: your database has settings that decide which words it will even remember, and when one of them is wrong nothing reports an error — searches simply come back empty for certain words while others work perfectly.

The most common example is a limit on how long a word can be. Some database installations ship with that set to ten characters, which makes words like authentication, configuration and workstation silently unfindable while shorter words work fine. WAMP on Windows ships this way. D007 spots it and tells you the one line to change.

---

Where it came from

Asked for in discussion #53.

• 🛠️ Search corpus — Developer Guide — how it works underneath
• 🔍 Full-text search — the design — what was built, what was ruled out and why