Documents & Versions

What a Document Is

An uploaded file and a document are not the same thing. A document is a file with a life of its own: versions, a state, a type, and a list of the records it belongs to.

Where to find it

Architect Panel → Data:

• Documents — every document on the system
• Document Types — the kinds you allow, and the rules each one carries
• Document Library — the screen people use to find them

On a record, documents appear in the Documents pane, which is switched on per datastore.

One document, many records

The point of the object. A lease belongs to the property, the tenancy and the dispute; a survey belongs to two cases that turned out to be the same site. Attaching it in three places uploads it three times and produces three files that drift apart the first time one is corrected.

A document is stored once and linked to as many records as it genuinely belongs to. There is one file, and correcting it corrects it everywhere.

Versions are a chain, not a replacement

Uploading a new version does not overwrite the old one. Every version is kept with its own filename, size, author, date and comment, and the document points at whichever is current.

That is what makes “which version did we send them in March” answerable.

A state, and what it is for

Draft, final, superseded or withdrawn. The state is a statement about the document rather than a permission — it does not decide who may read it — and withdrawn is deliberately one-way. A withdrawn document that could be quietly reinstated is not withdrawn.

A type carries rules

A document type can restrict which file extensions it accepts, give the document a default classification, and require check-out before a new version may be added. Types are how “policies work like this and photographs work like that” stops being a convention people remember.

A reference, if you use one

Documents carry an optional reference alongside the title, so CON-2024-118 and Riverside lease both find the same thing. People search for whichever one they happen to know.

The file is not modified

Adopting an existing attachment as a document leaves the original upload field working exactly as before. The document is an additional way to reach the same bytes, not a migration.

Worked example

A housing team uploads a tenancy agreement against the tenancy record and links it to the property and to a later disrepair case. When the agreement is re-signed they add a version rather than a second file. Three teams see the current agreement, and the disrepair case can still show which version was in force when the complaint was made.

Recommendations

• Define types before you upload in bulk — a type’s rules apply to what comes after it.
• Link rather than re-upload. A second copy is a second answer.
• Use the reference if your organisation already has document numbers.
• Treat withdrawn as final. It cannot be undone.

Version History and Restore

Every version of a document is kept, can be downloaded on its own, and can be brought back — as a new version, never by rewinding.

Where to find it

On a record, open the Documents pane and press History against a document. Each version shows its number, filename, size, author, date and comment.

Restoring copies forward

The behaviour worth understanding before you need it. Restoring version 2 of a five-version document writes version 6, pointing at version 2’s file. Nothing is deleted and nothing is renumbered.

Setting the current version back to 2 is the obvious implementation and the wrong one: it makes versions 3 to 5 vanish from every reader while still existing, and “v5 was here yesterday” is not a state a document library may ever be in.

It also makes the operation safe to repeat and safe to undo. Restoring the restore is just another copy forward, so there is no state a nervous user can reach that they cannot leave.

Every version has its own download

Each link is built for that version and is checked again when it is followed. Handing somebody a URL is not the same as granting them access — the download gate runs either way.

What restore refuses

• The current version — copying it forward produces two identical versions and a history that says something happened when nothing did.
• A version whose file has gone — disposed of under retention. The version record deliberately outlives the file so a destruction certificate can say what was destroyed; restoring one would produce a current version that cannot be opened.
• Somebody else’s check-out — and it names who holds it.
• A withdrawn document.

Two versions can share one file

A natural consequence of copying forward, and the rest of the system expects it. The download gate authorises any version a stored file belongs to, and the access log records one entry per document.

A version is not a draft

If several people are working towards a new version, that is check-out, or a separate draft document. Every version added is visible to everyone who can read the document.

Worked example

A policy is updated, and a fortnight later somebody notices the new version dropped an appendix. The previous version is restored from the history pane; it lands as the newest version, the mistaken one is still there with its own date and author, and the audit trail shows exactly what happened and when.

Recommendations

• Write a version comment. It is the only place “what changed” is recorded.
• Restore rather than re-upload an old file — the chain stays honest.
• Check the history before assuming a document is wrong; it may be the version that is wrong.

Check-out and Check-in

Check-out is how two people editing the same document avoid producing two different version fives.

Where to find it

On a record, the Documents pane shows Check out against each document and Check in while you hold it. A padlock marks a document somebody else has out, and names them.

What it actually prevents

Nothing technical stops somebody opening a checked-out file. What a check-out prevents is the second upload: while you hold it, nobody else can add a version.

That is the failure it exists for. Two people working from the same v4 and both uploading a v5 does not produce a conflict anybody can see — it produces one v5 and one silently discarded afternoon.

A lock expires

Every check-out has an expiry, and a document stops being checked out the moment it passes — whether or not the housekeeping task has run. The task tidies the record; it does not enforce the rule.

That ordering matters. It means a stopped task engine cannot leave a document permanently checked out to somebody who has left.

An administrator can release one

For the case the expiry does not cover: somebody checked a document out, left, and the lock has weeks to run. The release is recorded — who broke it, and when — because breaking somebody’s lock is an event and not a tidy-up.

A type can require it

Document types have a require check-out setting. With it on, a new version cannot be added unless the person adding it holds the lock. That is the right default for controlled documents and the wrong one for photographs.

Check in when you are finished, not when you are done for the day

A lock held overnight is a lock nobody can work round. If you are not going to upload today, check it in.

Worked example

A fire risk assessment is checked out on a Monday for a site visit. A colleague opening the record sees the padlock and the name rather than uploading their own revision from a copy they had locally. The assessment comes back as v3 on the Wednesday, with a comment saying which sections changed.

Recommendations

• Require check-out on controlled document types and leave it off elsewhere.
• Set an expiry that matches the work — a day for an edit, not a month.
• Check in before you stop, even without a new version.
• Do not make releasing routine. A lock broken weekly is a lock nobody trusts.

Attaching an Existing Document

A document that already exists can be attached to another record rather than uploaded again. The picker only offers documents you can already read.

Where to find it

On a record, the Documents pane → Attach existing. Search by title or reference, then choose a role.

Attaching is an access decision

The thing to understand before pressing it. Everybody who can read this record will be able to read this document, because that is exactly how document access works.

So the picker never lists a document you cannot read yourself, and the confirmation says plainly what attaching will do. It says it twice on purpose: once on the panel and once in the confirm.

A role, in your own words

“Evidence”, “correspondence”, “signed copy”. There is no fixed vocabulary, because what a document is on a case is your language rather than the platform’s.

The picker offers the roles this datastore has used before, which is what stops one datastore accumulating “evidence”, “Evidence” and “evidnce”.

Documents already here are marked, not hidden

Somebody searching for a document they attached last week needs to see that it is already on the record, not to find it missing and attach it twice.

Attaching twice is harmless

The link is checked both ways and is idempotent under the same role, so a repeated attach does nothing rather than producing a duplicate.

Detaching is reversible

Removing a document from a record does not delete it, and Recently removed on the same pane puts it back. See Putting Back a Removed Document.

Worked example

A site survey is already filed against a planning application. A later enforcement case on the same site attaches the existing survey as “background” rather than asking the surveyor for another copy. One file, two cases, and everybody working the enforcement case can read it.

Recommendations

• Read the consequence before attaching to a case with a restricted audience.
• Reuse an existing role name rather than inventing a synonym.
• Attach rather than re-upload whenever the file is genuinely the same one.