What this is about
CRMS has a small, fixed vocabulary. In the code, every word stands for exactly one thing. Once you know these words, you can read every other page of this module.
The template as a tree
flowchart TD
K["Template with key audit-report"] --> ES["Edition SYSTEM"]
K --> ET["Edition TENANT (tenant A)"]
K --> EU["Edition USER (one person)"]
ET --> VDE["Language variant de"]
ET --> VEN["Language variant en"]
VDE --> D["Draft: can be changed freely"]
VDE --> R1["Revision 1: superseded"]
VDE --> R2["Revision 2: published"]
A template has a key. For this key there can be several editions, one per owner. Every edition has language variants. Every variant has a draft and a chain of revisions.
Around the template
| Term | In the code | What it is |
|---|---|---|
| Template | – | What describes a report: a FreeMarker text with placeholders, plus fields and assets |
| Key | TemplateKey | The fixed name of a template, for example audit-report. It applies in every scope and every language. Lowercase letters, digits and hyphens, starts with a letter, at most 128 characters |
| Scope | TemplateScope | Who an edition belongs to: SYSTEM to the platform, TENANT to a tenant, USER to a single person |
| Edition | Edition | The template as one owner keeps it. A key has at most one edition per owner. The edition sets the output type and the default language |
| Language variant | Variant | An edition in one language, for example de or de-CH. Every variant has its own chain of revisions |
| Draft | Draft | The working copy of a variant. You save it as often as you like. It belongs to no chain |
| Revision | ChainEntry of type REVISION | A submitted state: source, fields and assets. It is never changed again, only new entries are added |
| State of a revision | RevisionState | IN_REVIEW, REJECTED, PUBLISHED, SUPERSEDED, RETIRED. It is read from the chain, not stored |
| Field | FieldDeclaration | A value the template expects in the payload, with its type and whether it is required |
| Asset | Asset | A file that belongs to the revision: image, font or style sheet. The template names it asset:<name> |
Per variant, at most one revision is published. Only this one is rendered. How a revision gets there is described in The life cycle of a template.
Whoever renders gets the most specific edition in which a fitting revision is published: first their own (USER), then the tenant’s (TENANT), then the platform’s (SYSTEM). For the language it goes from de-CH to de to the edition’s default language. The details are described in How a template is found.
Around the result
| Term | In the code | What it is |
|---|---|---|
| Output type | OutputType | What the source of a template produces. It decides which formats the template can be rendered into |
| Format | OutputFormat | The file that comes out: HTML, PDF, DOCX, XLSX, CSV, ODS |
| PDF profile | PdfProfile | The standard a PDF is produced by: NONE, PDF_A_3A (long-term archive), PDF_UA (accessible), PDF_A_3A_UA (both). Only for PDF |
| Render request | RenderRequest | What an application wants from CRMS: key, format, mode, plus language, time zone, PDF profile, reference, payload and attachments |
| Payload | data | The data for exactly this report, as an object with at most two levels |
| Attachment | RenderAttachment | An image (PNG or JPEG) that belongs only to this one request. The template names it attachment:<name> |
| Mode | RenderMode | PREVIEW, FINAL or TRANSIENT |
| Reference | DocumentReference | The identifier of the business object in the application, for example the ID of an audit. Required for FINAL. CRMS does not read it, it only uses it as a name |
| Origin | RenderOrigin | Where a document comes from: key, scope, language variant, revision and its hash |
| Document chain | DocumentChainKey | All final documents for one template, one scope, one reference and one owner |
| Document revision | DocumentRevision | A final document as a link of its document chain. The next FINAL for the same reference becomes the next revision |
The three output types and their formats:
| DOCUMENT | WORD | TABLE | |
|---|---|---|---|
| The template writes | XHTML | WordprocessingML as one XML document (Flat OPC) | the CRMS table document: sheets, rows, typed cells |
| Formats | HTML, PDF | DOCX | XLSX, CSV, ODS |
More in Output types and formats.
All terms in one request
Render request
POST /crms/render
{
"template": "audit-report", ← template key
"format": "PDF", ← format, fits the output type DOCUMENT
"mode": "FINAL", ← mode
"reference": "audit-4711", ← reference, required for FINAL
"locale": "de-DE", ← language of the document
"timeZone": "Europe/Berlin", ← time zone for date and time
"pdfProfile": "PDF_A_3A", ← PDF profile
"data": { "customer": { "name": "ACME" } } ← payload
}Answer
200 OK
Content-Type: application/pdf
Crms-Template-Key: audit-report ← origin: key
Crms-Template-Scope: TENANT ← edition that won
Crms-Template-Variant: de ← language variant that was used
Crms-Template-Revision: 3f2c… ← revision of the template
Crms-Template-Revision-Hash: sha-256:9a1e…
Crms-Document-Revision: 7b04… ← only for FINAL
(the bytes of the PDF)In the example, de-DE was requested, and the tenant’s edition only had a variant de. CRMS then takes de.
The three modes
| PREVIEW | FINAL | TRANSIENT | |
|---|---|---|---|
| stored | never | yes, as a document revision | never |
| marker | watermark and marker crms-preview | none | only marker crms-transient in the metadata |
| needs a reference | no | yes | no |
| allowed for | every published template | every published template, if the installation stores document revisions | only system templates, and only if switched on |