From the click to the report

What this is about

Ben works for the customer nordbau. He has finished an audit and clicks “Create inspection report”. A few seconds later he has a PDF. In between, all three modules work together, and each one does exactly one thing:

• CDMS holds the data of the audit.
• CIAS says who is asking, for which tenant and with which roles.
• CRMS turns a template and data into a document, and keeps it when it is a record.

This page branches off From login to the data. Signing in, BFF and filter chain work exactly as described there. This page is about what comes after.

The whole path

This is the path when CRMS runs embedded in the application and Ben asks for a final report:

sequenceDiagram
    autonumber
    participant U as User
    participant F as BFF
    participant FK as Filter chain (CIAS)
    participant A as custom code of the application
    participant C as CDMS
    participant R as CRMS
    participant DB as Tenant DB
    participant S as File storage
    U->>F: clicks "Create inspection report"
    F->>FK: POST /api/rest/audit/report with bearer token
    FK->>FK: check token, tenant nordbau, gate, roles
    FK->>A: RequestContext filled
    A->>C: reads audit, questions, answers
    C->>DB: SELECT (database of nordbau)
    DB-->>C: rows
    C-->>A: objects
    A->>A: builds the payload, at most two levels
    A->>R: ReportRenderPort.render(FINAL, audit-report, audit-4711, payload)
    R->>FK: who is calling? (from the RequestContext)
    FK-->>R: Ben, nordbau, roles
    R->>DB: looks for the template (Ben, nordbau, system)
    R->>R: checks the payload
    R->>R: renders in the pool, seals the PDF
    R->>S: stores the encrypted bytes, locked
    R->>DB: appends the revision to the chain, journal
    R-->>A: RenderedDocument with revision
    A-->>F: PDF
    F-->>U: download

The following stages walk through the path slowly.

Stage 1: up to the application

As always, the browser calls a route of its BFF. The BFF sends the request with Ben’s access token to the backend. There it first runs through the filter chain of CIAS: check the token, determine the tenant, ask the tenant gate, build the effective roles. At the end there is the RequestContext, the note for exactly this request.

This is the same path as for every other request, station by station on From login to the data. If nordbau is not served, the report ends here with 403, before a single line of the application’s code runs.

Stage 2: the application collects the data

The generator does not create a route for “Create inspection report”. That is custom code of the application: a controller of its own, like the one the hub’s reports have, or a hook. Both are Spring beans, and both can have the CRMS port injected.

This is what the call looks like:

RenderedDocument document = renderer.render(RenderRequest.finalDocument(
    new TemplateKey("audit-report"),       // template key
    OutputFormat.PDF,
    new DocumentReference("audit-4711"),   // the chain: the audit's ID
    payload));                             // at most two levels

The reference is the ID of the business object in your application, here the ID of the audit. CRMS does not look into it; it files all final versions of the same report under it. What the payload may look like is on The payload and its check, all fields of the request on The render request.

Stage 3: CRMS asks CIAS who is calling

CRMS does not read a token. It asks CIAS for the caller, and CIAS answers from the RequestContext the filter chain has already filled:

Rendering needs no role. Every signed-in person may render, with every template they can see. Roles only matter when templates are edited and when stored documents are read, see The roles.

Stage 4: finding the template

The request only names the key audit-report. Which edition and which revision renders is decided by CRMS. An edition is the version of a template for one scope, that is for the system, a tenant or a person. The most specific one wins:

Embedded, the CRMS tables sit next to those of the application, in the same databases. Which language applies and how CRMS falls back is on How CRMS finds the template and Language and time zone.

Stage 5: check, render, answer

Up to the payload everything runs on the request’s thread, because only there is the RequestContext and with it the right database. The rendering itself runs in a bounded pool, see Execution and limits.

For FINAL the step that makes the report a record comes next:

What a revision records exactly is on What a final document is, how the chain exposes changes on The two hash chains.

Stage 6: back to Ben

The application hands the document to the BFF, the BFF to the browser. If something goes wrong, CRMS throws a CrmsException with a key, never a sentence. The application passes the key on unchanged and does not translate it. The frontend shows it in Ben’s language. The hub does it like this: it turns every CrmsException into its own error shape, with the same key and the status CRMS gives that key. The keys are on The error answer.

Embedded or as a separate service

Where CRMS runs, the hub derives from the runtime of the CRMS module, see Embedded or as a separate service. Your code calls the same port in both cases and gets the same objects and keys back. But different things happen on the way.

sequenceDiagram
    autonumber
    participant A as Application
    participant FK as Filter chain (CIAS)
    participant R as CRMS (in the process)
    participant DB as Tenant DB
    A->>R: render(…) as a method call
    R->>FK: who is calling?
    FK-->>R: Ben, nordbau, roles (from the RequestContext)
    R->>DB: find template, for FINAL write the chain
    R-->>A: RenderedDocument

sequenceDiagram
    autonumber
    participant A as Application
    participant CL as crms-client
    participant FK as Filter chain in the CRMS service
    participant K as Keycloak
    participant R as CRMS service
    participant DB as DB of the CRMS service
    A->>CL: render(…)
    CL->>CL: Ben's token from the running request
    CL->>FK: POST /crms/render, Authorization: Bearer (Ben's token)
    FK->>K: exchange the token for the service's client
    K-->>FK: token with the CRMS roles
    FK->>FK: tenant from the token, gate, roles
    FK->>R: RequestContext filled
    R->>DB: find template, for FINAL write the chain
    R-->>CL: bytes and Crms-* headers
    CL-->>A: the same RenderedDocument

Three consequences of the separate service:

• The roles come from the service’s client. The service exchanges Ben’s token for one for its own client. So Ben needs a document role at that client, not at the application’s client. See Token exchange.
• The tenant comes from the token only. crms-client forwards only the Authorization header, no tenant or user headers. The service determines the tenant as if the request came without these headers.
• Without a running request there is no token. A scheduled job in the application gets crms-authentication-required, and nothing is sent.

How the client turns answers into exceptions is on The client for the separate service.

Preview, final, transient

The path up to rendering is the same for all three modes. What happens afterwards differs:

A typical flow uses two modes: Ben first clicks “Preview” (PREVIEW), checks the result and then finishes (FINAL). Both calls take exactly the same path and render with the same template; only the second one stores something. All rules of the modes are on Preview, final, transient.

What travels in which call

Where the path ends when something is missing

Traps

Where to go next

• An inspection report over the years: the same report over years, with verification, legal hold and cancellation
• From login to the data: the path up to the application
• When CIAS is not reachable: for reports too
• What CRMS is and The render request
• Example: the hub’s reports: an embedded call with TRANSIENT