Worum es geht
CRMS hat ein kleines, festes Vokabular. Jedes Wort steht im Code für genau eine Sache. Wenn du diese Wörter kennst, kannst du jede andere Seite dieses Moduls lesen.
Die Vorlage als Baum
flowchart TD
K["Vorlage mit Schlüssel audit-report"] --> ES["Edition SYSTEM"]
K --> ET["Edition TENANT (Mandant A)"]
K --> EU["Edition USER (eine Person)"]
ET --> VDE["Sprachvariante de"]
ET --> VEN["Sprachvariante en"]
VDE --> D["Entwurf: frei änderbar"]
VDE --> R1["Revision 1: ersetzt"]
VDE --> R2["Revision 2: veröffentlicht"]
Eine Vorlage hat einen Schlüssel. Zu diesem Schlüssel kann es mehrere Editionen geben, eine je Eigentümer. Jede Edition hat Sprachvarianten. Jede Variante hat einen Entwurf und eine Kette von Revisionen.
Rund um die Vorlage
| Begriff | Im Code | Was es ist |
|---|---|---|
| Vorlage | – | Was einen Bericht beschreibt: ein FreeMarker-Text mit Platzhaltern, dazu Felder und Assets |
| Schlüssel | TemplateKey | Der feste Name einer Vorlage, zum Beispiel audit-report. Er gilt in jedem Scope und jeder Sprache. Kleinbuchstaben, Ziffern und Bindestriche, beginnt mit einem Buchstaben, höchstens 128 Zeichen |
| Scope | TemplateScope | Wem eine Edition gehört: SYSTEM der Plattform, TENANT einem Mandanten, USER einer einzelnen Person |
| Edition | Edition | Die Vorlage, wie ein Eigentümer sie führt. Ein Schlüssel hat höchstens eine Edition je Eigentümer. Die Edition legt den Ausgabetyp und die Standardsprache fest |
| Sprachvariante | Variant | Eine Edition in einer Sprache, zum Beispiel de oder de-CH. Jede Variante hat ihre eigene Kette von Revisionen |
| Entwurf | Draft | Die Arbeitskopie einer Variante. Du speicherst sie, so oft du willst. Sie gehört zu keiner Kette |
| Revision | ChainEntry vom Typ REVISION | Ein eingereichter Stand: Quelltext, Felder und Assets. Er wird nie mehr geändert, nur neue Einträge kommen dazu |
| Status einer Revision | RevisionState | IN_REVIEW (in Prüfung), REJECTED (abgelehnt), PUBLISHED (veröffentlicht), SUPERSEDED (ersetzt), RETIRED (zurückgezogen). Er wird aus der Kette gelesen, nicht gespeichert |
| Feld | FieldDeclaration | Ein Wert, den die Vorlage in der Payload erwartet, mit Typ und ob er Pflicht ist |
| Asset | Asset | Eine Datei, die zur Revision gehört: Bild, Schrift oder Stylesheet. Die Vorlage nennt sie asset:<name> |
Pro Variante ist höchstens eine Revision veröffentlicht. Nur diese wird gerendert. Wie eine Revision dahin kommt, steht unter Der Lebenszyklus einer Vorlage.
Wer rendert, bekommt die genaueste Edition, in der eine passende Revision veröffentlicht ist: erst die eigene (USER), dann die des Mandanten (TENANT), dann die der Plattform (SYSTEM). Bei der Sprache geht es von de-CH über de zur Standardsprache der Edition. Die Einzelheiten stehen unter Wie eine Vorlage gefunden wird.
Rund um das Ergebnis
| Begriff | Im Code | Was es ist |
|---|---|---|
| Ausgabetyp | OutputType | Was der Quelltext einer Vorlage erzeugt. Er entscheidet, in welche Formate sie gerendert werden kann |
| Format | OutputFormat | Die Datei, die herauskommt: HTML, PDF, DOCX, XLSX, CSV, ODS |
| PDF-Profil | PdfProfile | Die Norm, nach der ein PDF erzeugt wird: NONE, PDF_A_3A (Langzeitarchiv), PDF_UA (barrierefrei), PDF_A_3A_UA (beides). Nur für PDF |
| Render-Anfrage | RenderRequest | Was eine Anwendung von CRMS will: Schlüssel, Format, Modus, dazu Sprache, Zeitzone, PDF-Profil, Referenz, Payload und Anhänge |
| Payload | data | Die Daten für genau diesen Bericht, als Objekt mit höchstens zwei Ebenen |
| Anhang | RenderAttachment | Ein Bild (PNG oder JPEG), das nur zu dieser einen Anfrage gehört. Die Vorlage nennt es attachment:<name> |
| Modus | RenderMode | PREVIEW (Vorschau), FINAL (endgültig) oder TRANSIENT (flüchtig) |
| Referenz | DocumentReference | Die Kennung des Fachobjekts in der Anwendung, zum Beispiel die ID eines Audits. Pflicht für FINAL. CRMS liest sie nicht, es nutzt sie nur als Namen |
| Herkunft | RenderOrigin | Woher ein Dokument kommt: Schlüssel, Scope, Sprachvariante, Revision und deren Hash |
| Dokumentkette | DocumentChainKey | Alle endgültigen Dokumente zu einer Vorlage, einem Scope, einer Referenz und einem Eigentümer |
| Dokumentrevision | DocumentRevision | Ein endgültiges Dokument als Glied seiner Dokumentkette. Das nächste FINAL zur selben Referenz wird die nächste Revision |
Die drei Ausgabetypen und ihre Formate:
| DOCUMENT | WORD | TABLE | |
|---|---|---|---|
| Die Vorlage schreibt | XHTML | WordprocessingML als ein XML-Dokument (Flat OPC) | das CRMS-Tabellendokument: Blätter, Zeilen, Zellen mit Typ |
| Formate | HTML, PDF | DOCX | XLSX, CSV, ODS |
Mehr dazu unter Ausgabetypen und Formate.
Alle Begriffe in einer Anfrage
Render-Anfrage
POST /crms/render
{
"template": "audit-report", ← Schlüssel der Vorlage
"format": "PDF", ← Format, passt zum Ausgabetyp DOCUMENT
"mode": "FINAL", ← Modus
"reference": "audit-4711", ← Referenz, Pflicht für FINAL
"locale": "de-DE", ← Sprache des Dokuments
"timeZone": "Europe/Berlin", ← Zeitzone für Datum und Uhrzeit
"pdfProfile": "PDF_A_3A", ← PDF-Profil
"data": { "customer": { "name": "ACME" } } ← Payload
}Antwort
200 OK
Content-Type: application/pdf
Crms-Template-Key: audit-report ← Herkunft: Schlüssel
Crms-Template-Scope: TENANT ← Edition, die gewonnen hat
Crms-Template-Variant: de ← Sprachvariante, die genutzt wurde
Crms-Template-Revision: 3f2c… ← Revision der Vorlage
Crms-Template-Revision-Hash: sha-256:9a1e…
Crms-Document-Revision: 7b04… ← nur bei FINAL
(die Bytes des PDF)Im Beispiel wurde de-DE angefragt, und die Edition des Mandanten hatte nur eine Variante de. CRMS nimmt dann de.
Die drei Modi
| PREVIEW | FINAL | TRANSIENT | |
|---|---|---|---|
| gespeichert | nie | ja, als Dokumentrevision | nie |
| Kennzeichen | Wasserzeichen und Merkmal crms-preview | keins | nur Merkmal crms-transient in den Metadaten |
| braucht eine Referenz | nein | ja | nein |
| erlaubt für | jede veröffentlichte Vorlage | jede veröffentlichte Vorlage, wenn die Installation Dokumentrevisionen speichert | nur Systemvorlagen, und nur wenn eingeschaltet |