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.

---

Attachments

The text inside attachments is searched, so a phrase buried in a spreadsheet somebody sent two years ago will turn up.

Read straight away	Read once you add a document reader
Word (.docx), Excel (.xlsx), PowerPoint (.pptx)	PDF
Plain text, .csv, .log, .md, .json, .xml	Older Office files (.doc, .xls, .ppt)
	Scanned documents and photographs of text

A file is read once, when it arrives. Nothing needs running on a schedule for the left-hand column.

Reading PDFs and scanned documents

Those need a separate document-reading service, because reliably pulling text out of a PDF is a genuinely hard problem — and a scanned invoice is harder still, since it contains no text at all, only a picture of text.

Set one up under System → Integrations → Apache Tika. It is one command to run and one address to paste in, and the page walks you through it. Once it is connected FreeITSM will read PDFs, older Office files, and run character recognition over scans and photographs — a picture of an invoice becomes searchable text.

If you have Docker, that command is:

docker run -d --name tika --restart unless-stopped \
  -p 127.0.0.1:9998:9998 apache/tika:latest-full

Then paste http://127.0.0.1:9998 into the settings page and press Test connection. There is no account to create and no key to paste, because there is nobody on the other end to have an account with.

⚠️ Use the -full image, and bind it to localhost. Two details that matter more than they look:

• The plain apache/tika:latest has no OCR engine. With it, PDFs and older Office files read perfectly well and scans come back successfully with no text in them — the one failure the status screen cannot flag, because as far as it is concerned the file was read.
• -p 127.0.0.1:9998:9998 keeps it reachable only from that machine. Tika has no authentication of its own, so it must never be exposed beyond a network you control.

Switching it on automatically queues everything that could not be read before, so attachments already sitting on your tickets are picked up without a rebuild.

The full list it adds:

	Formats
PDF	.pdf
Legacy Office	.doc .xls .ppt
OpenDocument and RTF	.odt .ods .odp .rtf
Forwarded mail	.eml .msg
Scans and photos, by OCR	.png .jpg .tif .bmp .gif .heic .webp

Because those take much longer to read than a Word file, they are done in the background. Tickets → Settings → Indexing decides when: on a schedule, or a few at a time while people are using FreeITSM. Both are on to begin with, so it works whether or not you run scheduled tasks.

If a document is not turning up

System → Search tells you, by name. As well as the totals, it lists the attachments that are not searchable — the file, the ticket it is on, and why: too large, format not supported, or could not be read.

That matters because a search that silently found nothing, when the file was never readable in the first place, teaches you the information is not there. Seeing the filename and the reason tells you to go and open it yourself instead.

What is still not searched

Filenames. Searching inside tickets matches the contents of an attachment, not what it is called.

---

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