Worum es geht
Läuft CRMS als eigener Dienst, braucht die Anwendung einen Weg dorthin. Das ist crms-client. Es bietet dieselben Ports wie das eingebettete CRMS. Ein Port ist eine Java-Schnittstelle, über die deine Anwendung CRMS aufruft. Hinter dem Port steckt hier kein Renderer, sondern ein HTTP-Aufruf an den Dienst.
Wann der Client gilt
Die Betriebsart steht in codamai.crms.placement (CODAMAI_CRMS_PLACEMENT). Der Hub leitet sie ab, je nachdem, in welche Laufzeit das CRMS-Modul gelegt wird.
placement | Im Build | Der Start schlägt fehl, wenn |
|---|---|---|
local | das eingebettete CRMS und die Formatmodule | das eingebettete CRMS fehlt |
remote | crms-client | crms-client fehlt, oder der Renderer oder die HTTP-Schnittstelle von CRMS dabei sind |
Mehr unter Eingebettet oder getrennt.
Was der Client anbietet
| Port und Methode | Route am Dienst |
|---|---|
ReportRenderPort.render | POST /crms/render |
ReportRenderPort.renderTo | POST /crms/render, die Antwort fließt beim Empfang direkt in deinen OutputStream |
ReportRenderPort.validate | POST /crms/render/validate |
CapabilitiesPort.capabilities | GET /crms/capabilities |
DocumentArchivePort.read | GET /crms/documents/{revision} |
DocumentArchivePort.revisions | GET /crms/documents?template=…&scope=…&reference=… |
DocumentArchivePort.verify | POST /crms/documents/{revision}/verify |
DocumentArchivePort.setLegalHold / releaseLegalHold | POST /crms/documents/{revision}/legal-hold / …/release |
DocumentArchivePort.erase | POST /crms/documents/{revision}/erase |
Das Bearbeiten von Vorlagen ist kein Port. Ein Vorlagen-Editor ruft die Vorlagenrouten des Dienstes direkt auf, siehe Die Endpunkte.
Das Token der Person, kein Diensttoken
crms-client schickt bei jedem Aufruf das Token der Person mit, deren Anfrage die Anwendung gerade beantwortet. Unverändert. Der CRMS-Dienst tauscht es dann gegen eines für seinen eigenen Client. So steht an jeder Revision und jedem Dokument die Person, die es ausgelöst hat, und nicht „der Dienst“.
sequenceDiagram
participant B as Benutzer
participant A as Anwendung
participant C as CRMS-Dienst
participant I as CIAS im Dienst
B->>A: Anfrage mit Bearer-Token
A->>C: POST /crms/render, dasselbe Bearer-Token
C->>I: Token prüfen und tauschen
I-->>C: Person, Mandant, Rollen des CRMS-Clients
C-->>A: Dokument oder Fehlerantwort
A-->>B: Antwort
Wann: der Normalfall, die Anwendung beantwortet gerade eine HTTP-Anfrage
Der Client nimmt das Token aus der Kopfzeile Authorization: Bearer … dieser Anfrage.
Ergebnis: der Aufruf geht im Namen dieser Person
Wann: ein Hintergrund-Job, ein Timer, ein eigener Thread
Es gibt keine Person, also gibt es kein Token. Der Client schickt nichts.
Ergebnis: CrmsException mit crms-authentication-required
Wann: die Anwendung stellt eine eigene Bean vom Typ CallerToken bereit
Der Client fragt diese Bean nach dem Token statt der laufenden Anfrage.
Ergebnis: der Aufruf geht mit dem Token, das die Bean liefert
Wie der Tausch im Dienst funktioniert, steht unter Token-Tausch. Welche Rollen der Dienst dann sieht, unter Die Rollen.
Einstellungen
| Property | Variable | Standard | Bedeutung |
|---|---|---|---|
codamai.crms.client.url | CODAMAI_CRMS_CLIENT_URL | keiner, Pflicht | http- oder https-Adresse des Dienstes. Die Routen hängen darunter: aus https://crms.example.com wird https://crms.example.com/crms/render |
codamai.crms.client.connect-timeout | CODAMAI_CRMS_CLIENT_CONNECT_TIMEOUT | PT5S | wie lange der Client auf eine Verbindung wartet |
codamai.crms.client.timeout | CODAMAI_CRMS_CLIENT_TIMEOUT | PT2M | wie lange ein ganzer Aufruf dauern darf |
Die Werte sind ISO-8601-Dauern: PT5S heißt fünf Sekunden, PT2M zwei Minuten. Fehlt die Adresse oder ist sie keine http- oder https-Adresse, startet die Anwendung nicht. Eine Dauer von null oder kleiner auch nicht.
Der Standard von timeout ist länger als die Render-Zeitgrenze des Dienstes (Standard PT30S). So kommt ein langsames Dokument als render-timeout des Dienstes zurück, statt dass der Client vorher aufgibt.
Wie Antworten zurückkommen
| Status | Fehlerantwort mit messageKey? | Was dein Code bekommt |
|---|---|---|
| 2xx | – | das Objekt, wie eingebettet: RenderedDocument, Capabilities, ArchivedDocument … |
| Fehler | ja, payload-rejected | PayloadRejectedException mit denselben violations |
| Fehler | ja | CrmsException mit demselben Schlüssel und denselben Parametern |
| 401 | nein | crms-authentication-required |
| 403 | nein | crms-access-denied |
| anderer | nein | crms-unavailable |
Ein 401 oder 403 ohne Fehlerantwort kommt von der Sicherheitskette des Dienstes, bevor CRMS die Anfrage gesehen hat. crms-unavailable heißt: Der Dienst war nicht erreichbar, hat nicht rechtzeitig geantwortet, oder die Antwort kam nicht von CRMS, etwa die Seite eines Proxys oder eine fehlende Route. Auch eine erfolgreiche Antwort, der etwas fehlt, ist crms-unavailable. Ein halbes Objekt gibt der Client nie zurück.
Werte unterwegs
- Daten reisen so, wie JSON sie trägt. Datum und Uhrzeit als ISO-8601-Text, Dezimalzahlen mit ihren Nachkommastellen:
12.50bleibt12.50. Sonst würde eine Vorlage etwas anderes drucken als eingebettet. - Was JSON nicht tragen kann, lehnt schon der Client ab, als
payload-rejectedmit derselben Regel wie die eingebettete Prüfung (value-type-unsupported,key-invalid). - Mit Anhängen wird komprimiert. Hat eine Render-Anfrage Bilder als Anhang, schickt der Client sie mit
Content-Encoding: gzip. Base64 macht Bilder um ein Drittel größer, gzip holt fast alles davon zurück. - Keine Weiterleitungen. Antwortet die Adresse mit einer Weiterleitung, folgt der Client ihr nicht. Die Antwort ist dann
crms-unavailable.