Adopting an Attachment
Everything else in this section applies to documents. A file uploaded through an ordinary file field on a record is not one — and on an existing installation there are thousands of them.
Where to find it
Architect Panel → Datastores, edit the datastore, and tick Attachments Become Documents. The work is done by the Adopt Uploads As Documents task, under Automation & Tasks.
What adopting gains you
Version history, restore, classification, an access log, content search, library columns, a review cycle, and disposal with the record. Nothing is copied and nothing moves: the upload field goes on working exactly as before, and the document is an additional way to reach the same file.
Why it is a task and not automatic
A file is uploaded against a field before the record it belongs to exists, which is why the association can only be worked out afterwards by reading the record. A sweep also catches files that arrived by any route — the record screen, the API, the mobile app — and is safe to run again.
The first run is a backfill
Which is why the task ships disabled and in preview mode. Ticking the box on a datastore with eleven years of attachments means adopting eleven years of attachments, and that is not something to arrange by accident.
Read the preview, for one specific reason
The preview counts what it would adopt and then samples storage to see how many of those files can actually be reached.
That matters more than it sounds. On any installation whose database has been copied from elsewhere, file rows routinely point at objects that are not in this installation’s storage. Adopting them fills the extraction queue with “the file could not be reached” and looks exactly like a broken system. Where everything sampled is missing, the preview says so in capitals.
Running it again creates nothing
A file that is already a document is recognised and skipped. The task runs hourly once armed, which is how a file uploaded this morning becomes searchable this afternoon.
Adopted files are queued, not read
Text extraction happens on its own schedule, because opening every file is a network fetch per document on S3 and does not belong inside a sweep holding a thousand of them.
It is per datastore, images included
A datastore of signature images or avatars should simply not turn it on. Indexing images needs OCR; adopting them without it gains version history and an access log and no searchability.
Worked example
A team ticks the box on their case datastore and runs the task in preview. It reports 4,180 attachments, of which 25 sampled files were all reachable. They enable it out of hours; the first run adopts the lot, the index catches up overnight, and content search covers eleven years of correspondence the next morning.
Recommendations
- Preview before arming, always, and read the storage line.
- Start with one datastore that matters, not all of them.
- Do not tick it on image-only datastores.
- Expect the first run to be long and the rest to be nothing.