Attached Documents

Attached documents

Attach files — or links to files you keep somewhere else — to contracts, assets, knowledge articles, problems and changes.

Asked for in discussion #76 by dschipfel: "records often require supporting documents, yet users must store files externally or reference them through notes instead of attaching directly."

For how it works underneath, see Attached documents — Developer Guide and Attached documents — permissions and search.

---

1. A file, or a link to one

The panel takes either, and treats them the same afterwards:

A file	Drag it onto the box, or click to choose one. FreeITSM stores it.
A link	Paste a URL to the document where it already lives — SharePoint, Google Drive, a network share exposed over the web, whatever you use. FreeITSM stores the address, not the document.

This is deliberate, and it is the point of the design. You are not being asked to move anything. If you already run a document management system, keep running it — attach links and FreeITSM becomes the index that says which documents matter to this contract. If you do not, attach the files and FreeITSM holds them. Most people end up doing both, and the list looks the same either way.

One thing worth knowing about links: FreeITSM cannot read the far end. A linked document is findable by the name and description you give it and nothing else, so the description is worth writing properly — it is all search has.

---

2. Where you will find it

Module	Where
Contracts	On the contract form, under Documents
Assets	A Documents tab beside Devices, Software and Tickets
Knowledge	Below the article
Problems	Its own section in the problem detail
Changes	Its own section in the change detail

Tickets are the deliberate exception — they already have attachments, arriving by email, with their own viewer. Giving a ticket two differently-behaved attachment boxes would be worse than giving it one.

---

3. One document, several records

This is the part that makes it more than a filing cabinet.

A warranty covering eleven laptops is one document attached eleven times, not eleven copies. Upload it once, then on each of the other assets start typing its name in "Or attach a document already in FreeITSM" and pick it.

Every document carries an ⓘ. Click it and you see everywhere that document lives:

morning-checks-2026-02-17.pdf
1.3 MB · by Ed Mozley · 2026-08-17
Searchable — 638 characters of text indexed.

ATTACHED TO
  • Asset: ACERLAPTOP
  • Contract: Hardware Supply Agreement

Which matters because of the next section.

Removing is not deleting

Remove takes the document off this record. If it is attached to anything else, it stays there and stays readable — you have detached it, not deleted it. Only when the last record lets go is the document actually deleted and its file removed.

The panel tells you when that has happened, rather than leaving you to guess which of the two things you just did.

---

4. Who can see a document

A document has no permissions of its own. It is visible if — and only if — you can see at least one of the things it is attached to.

• Can you see the contract? Then you can read its documents.
• Can you not? Then the document is not in the list, not in search, not in ⌘K, and not available at its own web address either.

Nothing to configure. It follows the access people already have, and it keeps following it: change somebody's access tomorrow and the answer changes with it, because the question is asked when they ask it rather than written down when the file was uploaded.

The consequence worth understanding

Attaching a document somewhere widens who can read it.

Attach a confidential contract PDF to a task the whole team can see, and the whole team can now read that PDF. That is not a bug — it is the same rule read forwards, and it is what makes the feature useful. But it means the act of attaching is a decision about access.

So the interface tries to make that visible rather than surprising:

• when you pick an existing document, it tells you where it already lives, in amber, before you click;
• the ⓘ lists every record it is on;
• if some of those are records you cannot see, it says "And 2 other records you do not have access to" — a count, never a name, because naming them would leak the very thing the rule protects.

---

5. Finding things

By name — ⌘K (Ctrl-K) matches a document's name, title and description, and shows where each one is attached.

By what is inside it — the text of an attached PDF, Word file or spreadsheet is read in the background and indexed, so searching for a phrase finds the document containing it under a Found inside documents heading. That is the difference between finding the file you already knew the name of, and finding the contract that happens to mention a supplier you are chasing.

Reading PDFs and scanned images needs Apache Tika configured under System → Search. Plain text and Office files are read without it. If Tika is not running, nothing breaks and nothing is lost — those documents are simply findable by name until it is, and then they catch up on their own.

The ⓘ tells you which state a document is in, because these are genuinely different and otherwise look identical:

It says	It means
Searchable — 638 characters of text indexed	Its contents are in the index
Not searchable yet — the text is still being read	Queued. Nothing is wrong
Its contents cannot be read	An image, or a format nothing can extract. Name and description still work

---

6. What is allowed

• File types are the same allow-list as ticket attachments, set at System → Security. You can narrow it; you cannot widen it to anything executable.
• Size is capped at 10 MB per file by default.
• Stored files are never served directly. They are only ever handed over by FreeITSM after it has checked who is asking — see the permissions guide for what that means for your web server.
• Every download is recorded — who, which document, when.

---

7. Keeping it tidy

Two jobs want a clock rather than a page load, and both are optional:

php scripts/documents_maintenance.php

It reads the text out of newly attached files, and clears up documents whose records have since been deleted. Every five minutes is plenty.

Without it nothing breaks and nothing leaks — uploading already reads one file, and a document whose record was deleted is invisible immediately. What you get is documents becoming searchable promptly instead of waiting for the next upload, and disk that does not slowly fill with files nobody can reach.

---

Related pages

• Attached documents — Developer Guide — the schema, the API and how to add a module
• Attached documents — permissions and search — how visibility is decided and enforced
• Searching inside tickets — the same extraction pipeline, for email attachments
• Security — upload handling and the guarded folders