CodamAIDocs
Topicdone

What a final document is

A final document is a revision of its document chain: what defines the chain, what a revision records, and what happens when it is stored.

Variants
first revision of a chainnext revision of the same chaindocument revisions switched off

What this is about

When an application renders a report with mode: FINAL, CRMS returns the document to it and keeps it as well. It becomes a revision: a version that never changes, in a document chain. A document chain collects all final versions of a report about the same business object, for example all inspection reports for the audit audit-4711.

How FINAL differs from PREVIEW and TRANSIENT is described in The three modes.

What defines a chain

A chain is defined by four values. CRMS computes the chain’s id from them. The same four values always give the same chain.

ValueWhere it comes fromExample
Ownerthe tenant from the token. Without a tenant, the systemacme
Template keytemplate from the requestaudit-report
Scopethe scope of the template edition that was actually renderedTENANT
Referencereference from the request: the id of the business object in your applicationaudit-4711

For CRMS the reference is only text. CRMS does not look into it. It is required for FINAL, 1 to 255 characters long, without blanks at the start or end and without control characters. If it is missing, CRMS refuses the request with a violation on the field reference.

Request
POST /crms/render
{
  "template": "audit-report",
  "format": "PDF",
  "mode": "FINAL",
  "reference": "audit-4711",      ← names the chain
  "locale": "de-DE",
  "data": { "customer": { "name": "ACME" } }
}
Response
200 OK
Content-Type: application/pdf
Crms-Document-Revision: 7c1e…    ← the new revision
Crms-Template-Key: audit-report
Crms-Template-Scope: TENANT
Crms-Template-Revision-Hash: sha-256:9f86…
(the document's bytes)

What happens when it is stored

  1. 1
    Client→CRMS
    sends a render request with mode: FINAL and reference
  2. 2
    CRMS
    checks whether this installation stores final documents
  3. 3
    CRMS
    no → 409 document-revisions-disabled
  4. 4
    CRMS
    renders the document. A PDF then gets the seal if the installation seals
  5. 5
    CRMS
    creates a key just for this document and encrypts the bytes with it
  6. 6
    CRMS→File storage
    stores the encrypted bytes locked until the retention ends
  7. 7
    CRMS→Database
    appends the revision to the chain and writes an entry document-stored into the journal
  8. 8
    CRMS→Client
    returns the document
    Result: The document is stored. The header Crms-Document-Revision names the revision

The bytes only come back once they are stored. So there can be no final document that your application holds and CRMS does not.

The journal is the second record next to the chain, one per tenant. More in The two hash chains.

What a revision records

A revision carries everything you need later to show how the document came about:

ItemWhat for
number in the chainposition, from 1, without gaps
template key, scope, language variant, template revision and its hashbinds the document to exactly one approved version of the template
format and PDF profilewhat was produced
content hash (SHA-256 of the bytes) and sizeshows that the bytes are unchanged
payload hashshows which data it was rendered with
whether the payload is kept encryptedsee below
id of the document keythe key the bytes are encrypted with
object key and version in the storagewhere the bytes are
retainUntiluntil when the document is kept
tenant, user, time (UTC, to the microsecond)who produced it and when
language and time zonehow numbers and dates were formatted
previous hash and own hashthe chaining

A hash is a short fingerprint of data. If a single bit changes, the whole hash changes. CRMS always writes hashes with the algorithm in front, for example sha-256:9f86….

The payload

The payload is the data the document was rendered with. Before hashing, CRMS brings it into a fixed form: canonical JSON, integers stay numbers, decimals and dates become text. So the same data always gives the same hash.

  • The payload hash is always stored.
  • The payload itself is kept, encrypted with the same document key, as long as CODAMAI_CRMS_DOCUMENT_STORE_PAYLOAD is on (default true).

When FINAL is accepted

Document revisions on?Reference given?Attachments included?What happens
no––409 document-revisions-disabled
yesno–422, violation on the field reference
yesyesyes422 attachments-not-for-final
yesyesnothe document is stored and returned

Document revisions are on by default (CODAMAI_CRMS_DOCUMENT_REVISIONS=true). Then the installation needs a retention period and a storage, or it does not start. See Retention and Storage on WORM.

Reading the revisions of a chain

Request
GET /crms/documents?template=audit-report&scope=TENANT&reference=audit-4711
Response
[
  {
    "revision": "7c1e…",
    "number": 1,                       ← oldest first
    "format": "PDF",
    "template": "audit-report",
    "scope": "TENANT",
    "variant": "de",
    "templateRevision": "a2f0…",
    "templateRevisionHash": "sha-256:9f86…",
    "storedAt": "2026-10-17T09:12:44.123456Z",
    "retainUntil": "2036-10-17T09:12:44.123456Z",
    "legalHold": false,
    "erased": false,
    "contentHash": "sha-256:3b1d…"
  }
]

All endpoints for documents and who may call them are listed in Verify and read.

Pitfalls

Next

Search