Beispiel: die Berichte des Hubs

Worum es geht

Der Hub erzeugt für jedes Projekt drei Dokumente: die Architektur nach arc42, eine Übersicht zum Datenschutz (welche Daten personenbezogen oder vertraulich sind) und ein Betriebshandbuch (Runbook). Er rendert sie mit einem eingebetteten CRMS. Am Hub siehst du, wie die Teile dieses Kapitels zusammenspielen.

Wie der Hub CRMS einrichtet

Der Hub ist selbst eine CDMS-Anwendung mit einem CRMS-Modul in ihrer eigenen Laufzeit. CRMS ist also eingebettet.

Einstellung	Wert	Woher
`codamai.crms.placement`	`local`	Rahmen der Anwendung
Dokumente ablegen	aus	CRMS-Modul, `documentRevisions: false`
Siegel	`none`	CRMS-Modul, `sealMode: NONE`
Scopes	nur `SYSTEM`	CRMS-Modul, `templateScopes: SYSTEM`
Formate	PDF und DOCX, dazu das eingebaute HTML	`pom.xml` mit `crms-format-pdf` und `crms-format-word`
Freigabestufen für `SYSTEM`	keine	CRMS-Modul
`codamai.crms.transient-documents`	`true`	Konfiguration der Anwendung, kein Feld des Moduls

Weil keine Dokumente abgelegt werden, steht crms-storage-s3 nicht in der pom.xml. Bucket, S3-Zugang und Dokumentschlüssel braucht der Hub nicht. Pflicht bleibt der Zeitstempel-Schlüssel CODAMAI_CRMS_TSA_KEYSTORE: Auch das Journal der Vorlagen wird verankert.

Zwei Vorlagen je Bericht

In CRMS entscheidet der Ausgabetyp einer Vorlage, welche Formate sie erzeugen kann (siehe Ausgabetypen und Formate). Ein Bericht in PDF und Word braucht deshalb zwei Vorlagen:

Bericht	`DOCUMENT`-Vorlage (HTML, PDF)	`WORD`-Vorlage (DOCX)
arc42	`arc42`	`arc42-word`
Datenschutz	`privacy`	`privacy-word`
Betriebshandbuch	`runbook`	`runbook-word`

Jede Vorlage gibt es auf Deutsch und Englisch. Die Quellen liegen im Build des Hubs unter crms-templates/<schlüssel>/de.xhtml.ftl und en.xhtml.ftl, die Word-Vorlagen als de.xml.ftl und en.xml.ftl.

Die Vorlagen kommen über den normalen Weg

Es gibt keinen Sonderweg für mitgelieferte Vorlagen. Der Hub bringt sie beim Start so in CRMS, wie jede Vorlage hineinkommt:

1

Hub
ist bereit und startet das Einspielen in einer Arbeitseinheit außerhalb einer Anfrage
2

Hub→CRMS
handelt als Plattform-Administrator mit dem Namen hub-backend
3

CRMS
legt fehlende Ausgaben im Scope SYSTEM an, je Bericht und Ausgabetyp, und je Sprache eine Variante
4

CRMS
Ist die Quelle gleich der veröffentlichten Revision?
5

CRMS
gleich → nichts geschieht, das Journal bleibt unverändert
6

Hub→CRMS
anders → speichert die Quelle als Entwurf und reicht ihn ein, mit der Begründung „Template shipped with the hub-backend build“
7

CRMS
Der Scope SYSTEM hat keine Freigabestufe, also wird die Revision sofort veröffentlicht

Ergebnis: Eine geänderte Vorlage im neuen Build wird genau eine neue Revision. Das Journal nennt, wer sie eingereicht hat und warum.

Mehr dazu unter Mitgelieferte Vorlagen.

Ein Bericht wird erzeugt

sequenceDiagram
    participant F as Hub-Frontend (BFF)
    participant H as Hub (ReportApi)
    participant C as CRMS (eingebettet)
    F->>H: POST /api/rest/cms/report/arc42/render?format=pdf&language=de
    H->>C: RenderRequest arc42, PDF, TRANSIENT, de, Daten
    C->>C: Systemvorlage? Transient erlaubt? Daten prüfen
    C-->>H: PDF mit Schlüsselwort crms-transient
    H-->>F: 200, als Download arc42.pdf

Das Frontend des Hubs bringt alle Daten mit, die das Dokument zeigt. Es macht sie dafür flach: CRMS nimmt höchstens zwei Ebenen an (siehe Payload-Prüfung). Die Dienste einer Laufzeit kommen deshalb als eigene Liste runtimeServices, und jeder Dienst nennt seine Laufzeit über die Position in runtimes.

Parameter	Werte	Wirkung
`{report}`	`arc42`, `privacy`, `runbook`	welcher Bericht. Ein anderer → 404 `report-template-unknown`
`format`	`pdf` (Vorgabe), `docx`, `html`	`pdf` und `html` aus der `DOCUMENT`-Vorlage, `docx` aus der `WORD`-Vorlage. Ein anderes → 400 `report-format-unknown`
`language`	etwa `de`, `en`	die Sprache des Dokuments. Fehlt sie, bestimmt CRMS die Sprache aus der Anfrage
`filename`	Dateiname ohne Endung	Name des Downloads. Fehlt er, der Schlüssel des Berichts

HTML kommt zum Anzeigen im Browser zurück, PDF und DOCX als Download.

Das Diagramm als SVG

arc42 enthält ein Bild der Topologie, das für jedes Projekt anders aussieht. Es kommt als SVG-Text im Feld diagramSvg der Daten. Eine Vorlage darf Markup aus den Daten nicht einfach ausgeben. Deshalb setzt sie das Bild über die Funktion crms.svg, die CRMS bereitstellt:

<div class="figure">${crms.svg(diagramSvg)}<p class="caption">Abbildung 1: Systemübersicht (Ebene 1)</p></div>

CRMS prüft das SVG gegen eine Liste erlaubter Elemente, bevor es ins Dokument kommt. Siehe Bilder und SVG.

Format	Was aus dem SVG wird
PDF	Vektorgrafik im PDF
HTML	das SVG selbst, eingebettet
DOCX	CRMS rechnet es in ein PNG um und setzt es in der angegebenen Größe als Bild ein

Fehler

Was CRMS ablehnt, gibt der Hub unverändert weiter: denselben Schlüssel, mit dem Status, den CRMS ihm gibt.

Anfrage

POST /api/rest/cms/report/arc42/render?format=pdf
{ "runtimes": [ { "services": [ { "name": "…" } ] } ] }

Antwort

422
{
  "messageKey": "payload-rejected",
  "violations": [
    { "field": "runtimes[0].services", "rule": "depth-exceeded" }
  ]
}

Schlüssel	Status	Bedeutung
`template-not-found`	404	zu diesem Schlüssel gibt es keine veröffentlichte Vorlage
`payload-rejected`	422	die Daten verletzen eine Regel, `violations` nennt Feld und Regel
`template-svg-rejected`	422	das SVG enthält etwas, das nicht erlaubt ist
`render-capacity-exhausted`	503	zu viele Dokumente gleichzeitig
`render-timeout`	504	das Dokument wurde nicht rechtzeitig fertig

Alle Schlüssel und ihre Bedeutung stehen unter Fehler.

Beispiel: die Berichte des Hubs

Worum es geht

Wie der Hub CRMS einrichtet

Zwei Vorlagen je Bericht

Die Vorlagen kommen über den normalen Weg

Ein Bericht wird erzeugt

Das Diagramm als SVG

Fehler

Fallen

Weiter