The render request

What this is about

A render request tells CRMS which document you want: from which template, in which format, with which data. CRMS answers in the same call with the finished document.

You can ask CRMS in two ways. Embedded, CRMS runs inside your application, and you call a Java interface. Standalone, CRMS runs as a separate service, and you send the request over HTTP. The content of the request is the same in both cases. How the two operating modes come about is described in Embedded or standalone.

A request, field by field

POST /crms/render
Content-Type: application/json
Authorization: Bearer <token>
{
  "template": "audit-report",      ← template key, required
  "format": "PDF",                 ← format, required
  "mode": "FINAL",                 ← PREVIEW, FINAL or TRANSIENT, required
  "reference": "audit-4711",       ← your reference, required for FINAL
  "locale": "de-DE",               ← language, optional
  "timeZone": "Europe/Berlin",     ← time zone, optional
  "pdfProfile": "PDF_A_3A",        ← only for PDF, optional
  "data": {                        ← the payload
    "customer": { "name": "ACME" }
  },
  "attachments": []                ← pictures of this request, optional
}

HTTP 200
Content-Type: application/pdf
Content-Disposition: inline; filename="audit-report.pdf"
Crms-Template-Key: audit-report
Crms-Template-Scope: TENANT
Crms-Template-Variant: de
Crms-Template-Revision: 3f0c…
Crms-Template-Revision-Hash: sha-256:9a1e…
Crms-Document-Revision: 7b42…      ← only for FINAL
X-Content-Type-Options: nosniff

%PDF-1.7 …

The response headers tell you exactly what the document was made from: which template, from which scope (the level on which the template applies: system, tenant or user), which language variant, which revision (an approved, unchangeable version of the template) and its hash. How CRMS finds the template is described in How CRMS finds the template.

How CRMS reads the request

Over REST, CRMS reads the JSON body field by field. Strict rules apply:

• Unknown fields are refused (not-allowed). A misspelt name like refrence shows up at once instead of silently doing nothing.
• The wrong JSON type is invalid. CRMS converts nothing: 42 is not a template key.
• null counts like a missing field.
• Decimal numbers in data are read as exact decimals, not as floating-point numbers. An amount keeps exactly its digits.
• pdfProfile with a format other than PDF is not-allowed.
• All broken fields come in one answer: 422 validation-failed with violations.

The body is bounded before it is read. The limit follows from the payload limit, the attachment limit and some room for the other fields. If it is larger, CRMS answers 422 payload-rejected with the violation payload-too-large. The body may come compressed with Content-Encoding: gzip. The limit then applies to the unpacked bytes. Other encodings are 415 content-encoding-unsupported.

The stations before rendering

Before CRMS renders, it checks the request in this order. Each station can end the request.

Only after the last station does the real work start: run the template, produce the format, and for FINAL seal and store. What can go wrong there is described in Execution and limits. All errors come back in one shape, see Errors and message keys.

The ways to send a request

An embedded call from the hub looks like this. It renders a transient copy without a reference and without its own time zone:

RenderedDocument document = renderer.render(new RenderRequest(
    new TemplateKey("arc42"),       // template key
    Locale.forLanguageTag("de"),    // language, or null
    null,                           // time zone: TZ, then UTC
    OutputFormat.PDF,
    null,                           // PDF profile: the installation's default
    RenderMode.TRANSIENT,
    null,                           // reference: only for FINAL
    data));

What an installation offers

GET /crms/capabilities tells you what you can request: the offered formats, the default PDF profile, the admitted scopes, the installation’s languages, whether final documents are stored (documentRevisions), whether transient ones are allowed (transientDocuments) and the limits. Embedded, CapabilitiesPort returns the same. The values come from the configuration and do not change while running.

GET /crms/capabilities

{
  "formats": ["HTML", "PDF", "DOCX"],
  "defaultPdfProfile": "PDF_A_3A",
  "scopes": ["TENANT", "SYSTEM"],
  "locales": ["de", "en"],
  "documentRevisions": true,
  "transientDocuments": false,
  "limits": {
    "timeout": "PT30S",
    "maxOutputBytes": 52428800,
    "maxPayloadBytes": 5242880,
    "maxAttachmentCount": 200,
    "maxAttachmentBytes": 52428800
  }
}

Pitfalls

Next

• The payload and its check
• Preview, final, transient
• The REST endpoints