Example: the reports of the hub

What this is about

For every project, the hub produces three documents: the architecture according to arc42, an overview of privacy (which data is personal or confidential) and an operations runbook. It renders them with an embedded CRMS. The hub shows how the parts of this chapter work together.

How the hub sets up CRMS

The hub is itself a CDMS application with a CRMS module in its own runtime. So CRMS is embedded.

Setting	Value	From
`codamai.crms.placement`	`local`	scaffold of the application
store documents	off	CRMS module, `documentRevisions: false`
seal	`none`	CRMS module, `sealMode: NONE`
scopes	`SYSTEM` only	CRMS module, `templateScopes: SYSTEM`
formats	PDF and DOCX, plus the built-in HTML	`pom.xml` with `crms-format-pdf` and `crms-format-word`
approval stages for `SYSTEM`	none	CRMS module
`codamai.crms.transient-documents`	`true`	configuration of the application, not a field of the module

Because no documents are stored, crms-storage-s3 is not in the pom.xml. The hub needs no bucket, no S3 access and no document key. The timestamping key CODAMAI_CRMS_TSA_KEYSTORE stays required: the journal of the templates is anchored too.

Two templates per report

In CRMS, the output type of a template decides which formats it can produce (see Output types and formats). A report in PDF and Word therefore needs two templates:

Report	`DOCUMENT` template (HTML, PDF)	`WORD` template (DOCX)
arc42	`arc42`	`arc42-word`
privacy	`privacy`	`privacy-word`
runbook	`runbook`	`runbook-word`

Every template exists in German and English. The sources are in the build of the hub under crms-templates/<key>/de.xhtml.ftl and en.xhtml.ftl, the Word templates as de.xml.ftl and en.xml.ftl.

The templates take the normal path

There is no special path for shipped templates. At start, the hub brings them into CRMS the way every template gets in:

1

Hub
is ready and starts the seeding in a unit of work outside a request
2

Hub→CRMS
acts as a platform administrator with the name hub-backend
3

CRMS
creates missing editions in the scope SYSTEM, per report and output type, and one variant per language
4

CRMS
Is the source the same as the published revision?
5

CRMS
same → nothing happens, the journal stays unchanged
6

Hub→CRMS
different → saves the source as a draft and submits it, with the reason "Template shipped with the hub-backend build"
7

CRMS
The scope SYSTEM has no approval stage, so the revision is published at once

Result: A changed template in a new build becomes exactly one new revision. The journal names who submitted it and why.

A report is produced

sequenceDiagram
    participant F as Hub frontend (BFF)
    participant H as Hub (ReportApi)
    participant C as CRMS (embedded)
    F->>H: POST /api/rest/cms/report/arc42/render?format=pdf&language=de
    H->>C: RenderRequest arc42, PDF, TRANSIENT, de, data
    C->>C: System template? Transient allowed? Check data
    C-->>H: PDF with keyword crms-transient
    H-->>F: 200, as download arc42.pdf

The frontend of the hub brings all the data the document shows. It makes the data flat for this: CRMS accepts at most two levels (see Payload check). The services of a runtime therefore come as a list of their own, runtimeServices, and every service names its runtime by its position in runtimes.

Parameter	Values	Effect
`{report}`	`arc42`, `privacy`, `runbook`	which report. Another one → 404 `report-template-unknown`
`format`	`pdf` (default), `docx`, `html`	`pdf` and `html` from the `DOCUMENT` template, `docx` from the `WORD` template. Another one → 400 `report-format-unknown`
`language`	e.g. `de`, `en`	the language of the document. If it is missing, CRMS takes the language from the request
`filename`	file name without extension	name of the download. If it is missing, the key of the report

HTML comes back for display in the browser, PDF and DOCX as a download.

The diagram as SVG

arc42 contains a picture of the topology that looks different for every project. It arrives as SVG text in the field diagramSvg of the data. A template must not simply output markup from the data. So it places the picture through the function crms.svg, which CRMS provides:

<div class="figure">${crms.svg(diagramSvg)}<p class="caption">Figure 1: System overview (level 1)</p></div>

CRMS checks the SVG against a list of allowed elements before it goes into the document. See Pictures and SVG.

Format	What the SVG becomes
PDF	vector graphics in the PDF
HTML	the SVG itself, embedded
DOCX	CRMS converts it to a PNG and inserts it as a picture at its declared size

Errors

What CRMS refuses, the hub passes on unchanged: the same key, with the status CRMS gives it.

Request

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

Response

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

Key	Status	Meaning
`template-not-found`	404	there is no published template for this key
`payload-rejected`	422	the data breaks a rule, `violations` names field and rule
`template-svg-rejected`	422	the SVG contains something that is not allowed
`render-capacity-exhausted`	503	too many documents at once
`render-timeout`	504	the document was not finished in time

All keys and their meaning are listed in Errors.

Example: the reports of the hub

What this is about

How the hub sets up CRMS

Two templates per report

The templates take the normal path

A report is produced

The diagram as SVG

Errors

Pitfalls

Next