File versions

For audited file models every old state is kept. How the versions are stored, how revision and content belong together, and when content is simply overwritten.

Variants

audited → versionsnot audited → overwrittenrevision and version belong togetheraccess only through rollbackswitching on auditing laterno automatic cleanup

What this is about

When you upload new content for a file model, it replaces the old content. Whether the old one is lost is decided by a single switch: whether the model is audited. See What is audited.

How versions are stored

Three uploads to the same record of an audited model:

File in storage	Content	Role
`<fileId>`	“edition three”	current content, always under the name without suffix
`<fileId>.1790000200000`	“edition two”	version
`<fileId>.1790000100000`	“edition one”	version

Before every upload, CDMS renames the previous current content and appends a version identifier in the process. Then it stores the new content under the name without suffix. The identifier is a number, and larger means newer. It is stored in the record as fileVersion.

Revision and version belong together

fileVersion is a normal field of the record. That is why the history records it in every revision. So every revision knows which content was current back then:

flowchart LR
    R1["Revision 17 · ADD<br/>fileVersion 1790000100000"] --> V1["edition one"]
    R2["Revision 42 · MOD<br/>fileVersion 1790000200000"] --> V2["edition two"]
    R3["Revision 57 · MOD<br/>fileVersion 1790000300000"] --> V3["edition three (current)"]

Getting at an old version

There is no endpoint of its own for downloading an old version. The way leads through the history and a rollback:

1

Client→CDMS
POST /fileasset/f1…/history with ["name", "fileSize", "fileVersion"]

The revisions show when which content was uploaded and by whom.
2

Client→CDMS
POST /fileasset/f1…/rollback/42
3

CDMS→File storage
keeps the current content as a new version and copies version 1790000200000 to the current place
4

CDMS→Database
sets the record back to revision 42; that is itself a new revision

Result: GET /fileasset/f1…/file now returns "edition two". "Edition three" is kept as a version, so the rollback can be undone again.

Details in Rollback for files.

Audited or not

New upload to an existing record

Audited

old content becomes a version
history and rollback endpoints exist
every revision knows its content
storage needs grow with every upload

Not audited

old content is overwritten
no history, no rollback
restoring only from a backup of the infrastructure
storage needs stay at one file per record

Special cases

Versions over time

Switching on auditing laterSwitching off auditingDeleting the record

When: An existing file model is set to audited in the hub and generated again.

No migration is needed. Existing files simply have no versions yet. The first one is created at the next upload.

When: The model is set to not audited.

From then on, new uploads overwrite. Versions that already exist stay in the storage until the record is deleted.

When: DELETE on the file model, directly or through a cascade

The current content and all versions are removed.

Result: See Deleting file models.

Pitfalls

What comes next

How an upload replaces: Replacing and renaming
Back to an old state: Rollback for files
Where the files live: Storage layout and tenant isolation in storage