CodamAIDocs
Themafertig

Was ein endgültiges Dokument ist

Ein endgültiges Dokument ist eine Revision seiner Dokumentkette: was die Kette bestimmt, was eine Revision festhält und was beim Speichern passiert.

Ausprägungen
erste Revision einer Kettenächste Revision derselben KetteDokumentrevisionen ausgeschaltet

Worum es geht

Rendert eine Anwendung einen Bericht mit mode: FINAL, gibt CRMS ihr das Dokument zurück und behält es selbst. Es wird zu einer Revision: einem unveränderlichen Stand in einer Dokumentkette. Eine Dokumentkette sammelt alle endgültigen Fassungen eines Berichts über dasselbe Fachobjekt, zum Beispiel alle Prüfberichte zum Audit audit-4711.

Wie FINAL sich von PREVIEW und TRANSIENT unterscheidet, steht unter Die drei Modi.

Was eine Kette bestimmt

Eine Kette ist durch vier Werte festgelegt. CRMS berechnet aus ihnen die Kennung der Kette. Dieselben vier Werte ergeben immer dieselbe Kette.

WertWoherBeispiel
Eigentümerder Mandant aus dem Token. Ohne Mandant das Systemacme
Vorlagenschlüsseltemplate aus der Anfrageaudit-report
Scopeder Scope der Vorlagen-Edition, die tatsächlich gerendert wurdeTENANT
Referenzreference aus der Anfrage: die Kennung des Fachobjekts in deiner Anwendungaudit-4711

Die Referenz ist für CRMS nur ein Text. CRMS liest nicht hinein. Sie ist Pflicht bei FINAL, 1 bis 255 Zeichen lang, ohne Leerzeichen am Anfang oder Ende und ohne Steuerzeichen. Fehlt sie, lehnt CRMS die Anfrage mit einem Verstoß am Feld reference ab.

Anfrage
POST /crms/render
{
  "template": "audit-report",
  "format": "PDF",
  "mode": "FINAL",
  "reference": "audit-4711",      ← benennt die Kette
  "locale": "de-DE",
  "data": { "customer": { "name": "ACME" } }
}
Antwort
200 OK
Content-Type: application/pdf
Crms-Document-Revision: 7c1e…    ← die neue Revision
Crms-Template-Key: audit-report
Crms-Template-Scope: TENANT
Crms-Template-Revision-Hash: sha-256:9f86…
(die Bytes des Dokuments)

Was beim Speichern passiert

  1. 1
    Client→CRMS
    schickt eine Render-Anfrage mit mode: FINAL und reference
  2. 2
    CRMS
    prüft, ob diese Installation endgültige Dokumente speichert
  3. 3
    CRMS
    nein → 409 document-revisions-disabled
  4. 4
    CRMS
    rendert das Dokument. Ein PDF bekommt danach das Siegel, wenn die Installation siegelt
  5. 5
    CRMS
    erzeugt einen eigenen Schlüssel nur für dieses Dokument und verschlüsselt die Bytes damit
  6. 6
    CRMS→Dateispeicher
    legt die verschlüsselten Bytes gesperrt ab, bis die Aufbewahrung endet
  7. 7
    CRMS→Datenbank
    hängt die Revision an die Kette und schreibt einen Eintrag document-stored ins Journal
  8. 8
    CRMS→Client
    gibt das Dokument zurück
    Ergebnis: Das Dokument ist gespeichert. Der Header Crms-Document-Revision nennt die Revision

Die Bytes kommen erst zurück, wenn sie gespeichert sind. So kann es kein endgültiges Dokument geben, das deine Anwendung hat und CRMS nicht.

Das Journal ist das zweite Protokoll neben der Kette, je Mandant eines. Mehr dazu unter Die zwei Hash-Ketten.

Was eine Revision festhält

Eine Revision trägt alles, was man später braucht, um zu zeigen, wie das Dokument entstanden ist:

AngabeWofür
Nummer in der KettePosition, ab 1, ohne Lücken
Vorlagenschlüssel, Scope, Sprachvariante, Vorlagen-Revision und ihr Hashbindet das Dokument an genau einen freigegebenen Stand der Vorlage
Format und PDF-Profilwas erzeugt wurde
Inhalts-Hash (SHA-256 der Bytes) und Größebelegt, dass die Bytes unverändert sind
Payload-Hashbelegt, mit welchen Daten gerendert wurde
ob die Payload verschlüsselt aufbewahrt wirdsiehe unten
Kennung des Dokumentschlüsselsder Schlüssel, mit dem die Bytes verschlüsselt sind
Objektschlüssel und Version im Speicherwo die Bytes liegen
retainUntilbis wann das Dokument aufbewahrt wird
Mandant, Benutzer, Zeitpunkt (UTC, auf die Mikrosekunde)wer es wann erzeugt hat
Sprache und Zeitzonewie Zahlen und Daten formatiert wurden
vorheriger Hash und eigener Hashdie Verkettung

Ein Hash ist ein kurzer Fingerabdruck von Daten. Ändert sich ein einziges Bit, ändert sich der ganze Hash. CRMS schreibt Hashes immer mit Verfahren davor, zum Beispiel sha-256:9f86….

Die Payload

Die Payload sind die Daten, mit denen gerendert wurde. CRMS bringt sie vor dem Hashen in eine feste Form: kanonisches JSON, ganze Zahlen bleiben Zahlen, Dezimalzahlen und Datumswerte werden Text. So ergeben dieselben Daten immer denselben Hash.

  • Der Payload-Hash wird immer gespeichert.
  • Die Payload selbst wird verschlüsselt mit demselben Dokumentschlüssel aufbewahrt, solange CODAMAI_CRMS_DOCUMENT_STORE_PAYLOAD an ist (Standard true).

Wann FINAL angenommen wird

Dokumentrevisionen an?Referenz angegeben?Anhänge dabei?Was passiert
nein––409 document-revisions-disabled
janein–422, Verstoß am Feld reference
jajaja422 attachments-not-for-final
jajaneinDokument wird gespeichert und zurückgegeben

Dokumentrevisionen sind standardmäßig an (CODAMAI_CRMS_DOCUMENT_REVISIONS=true). Dann braucht die Installation eine Aufbewahrungsdauer und einen Speicher, sonst startet sie nicht. Siehe Aufbewahrung und Ablage auf WORM-Speicher.

Die Revisionen einer Kette lesen

Anfrage
GET /crms/documents?template=audit-report&scope=TENANT&reference=audit-4711
Antwort
[
  {
    "revision": "7c1e…",
    "number": 1,                       ← älteste zuerst
    "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…"
  }
]

Alle Endpunkte für Dokumente und wer sie aufrufen darf, stehen unter Prüfen und lesen.

Fallen

Weiter

Suchen