Konfiguration

Diese Seite beschreibt alle Konfigurationsmöglichkeiten der XJustiz-Werkzeuge: welche Dateien es gibt, was sich darüber steuern lässt und wie Änderungen wirksam werden. Sie richtet sich sowohl an Anwenderinnen und Anwender, die z. B. die Startseite anpassen möchten, als auch an IT-Fachpersonal, das den Server für den Produktivbetrieb konfiguriert.

Überblick: Was wird wo konfiguriert?

Alle Pfade beziehen sich auf das Installationsverzeichnis der XJustiz-Werkzeuge (der Ordner, in den das Auslieferungsarchiv entpackt wurde).

Konfigurationsort	Steuert	Änderung wirksam nach
`config/application.properties`	Server: Port, SSL/TLS, Upload-Limits, Logging	Neustart der Anwendung
`config/application-pdfName.properties`	Dateinamen der erzeugten PDF-Dokumente	Neustart der Anwendung
`tools/startseite-config.js`	Startseite der Demo-Anwendung (Kacheln, Texte, Farben)	Neuladen der Seite im Browser
`tools/loader-config.js`	Verhalten der lokalen Startseite `loader.html`	Neuladen der Seite im Browser
`formulare.json` (in der JAR)	Formularübersicht der Demo-Anwendung	Neustart der Anwendung
`schematrons/`	Eigene Schematron-Prüfregeln für die Validierung	Neustart der Anwendung
Startparameter (`start.sh` / `start.bat`)	Demo-Modus, Codelisten-Update, Proxy, temporäres Verzeichnis	Neustart der Anwendung

Faustregel

Alles, was der Server auswertet (config/, formulare.json, schematrons/, Startparameter), erfordert einen Neustart der Anwendung. Alles, was der Browser auswertet (tools/*.js), erfordert nur ein Neuladen der Seite.

Server-Konfiguration: `config/application.properties`

Die zentrale Konfigurationsdatei des REST-Servers. Sie liegt im Ordner config/ und wird beim Start der Anwendung eingelesen. Auslieferungszustand:

server.port=8888
server.ssl.key-store=config/SERVER_SSL_KEY.p12
server.ssl.key-store-password=123456
server.ssl.key-store-type=PKCS12
spring.jackson.date-format=org.openapitools.RFC3339DateFormat
spring.jackson.serialization.WRITE_DATES_AS_TIMESTAMPS=false
spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=10MB
server.tomcat.max-swallow-size=100MB
logging.level.root=INFO
logging.level.org.openapitools=INFO
logging.file.name=xjustiz-tools.log
logging.file.path=.

Port ändern

Der Server lauscht standardmäßig auf Port 8888. Um einen anderen Port zu verwenden:

server.port=9091

Port auch im Startskript und im Loader anpassen

Wenn Sie die Demo-Anwendung über start_demo.sh / start_demo.bat starten, muss dort die Variable SERVER_PORT auf denselben Wert gesetzt werden. Ebenso erwartet tools/loader-config.js den passenden Port (siehe Loader-Konfiguration).

Transportverschlüsselung (SSL/TLS)

Für den Produktivbetrieb müssen die drei SSL-Parameter an die eigene Betriebsumgebung angepasst werden:

Parameter	Bedeutung
`server.ssl.key-store`	Pfad zur Schlüsseldatei (Keystore)
`server.ssl.key-store-password`	Passwort des Keystores
`server.ssl.key-store-type`	Typ des Keystores: `PKCS12` oder `JKS`

Vorgehen:

Eigene Schlüsseldatei (z. B. mein-server.p12) in den Ordner config/ kopieren.

Die drei Parameter in config/application.properties anpassen:

server.ssl.key-store=config/mein-server.p12
server.ssl.key-store-password=IhrSicheresPasswort
server.ssl.key-store-type=PKCS12

Anwendung neu starten.

Mitgelieferten Beispiel-Schlüssel nicht produktiv verwenden

Die ausgelieferte Datei SERVER_SSL_KEY.p12 mit dem Passwort 123456 dient ausschließlich Testzwecken. Für den Produktivbetrieb muss ein eigenes Zertifikat hinterlegt werden.

Upload-Limits

Die maximale Größe hochgeladener Dateien (z. B. XJustiz-Nachrichten für die Validierung) ist standardmäßig auf 10 MB begrenzt. Für größere Nachrichten beide Werte erhöhen:

spring.servlet.multipart.max-file-size=50MB
spring.servlet.multipart.max-request-size=50MB

Logging

Die Anwendung schreibt ihr Protokoll in die Datei xjustiz-tools.log im Installationsverzeichnis. Anpassbar sind:

Parameter	Bedeutung	Beispielwerte
`logging.level.root`	Detailgrad des Protokolls	`ERROR`, `WARN`, `INFO`, `DEBUG`
`logging.file.name`	Name der Protokolldatei	`xjustiz-tools.log`
`logging.file.path`	Ablageort der Protokolldatei	`.` (Installationsverzeichnis), `/var/log/xjustiz`

Für eine Fehlersuche kann der Detailgrad vorübergehend erhöht werden:

logging.level.root=DEBUG

PDF-Dateinamen: `config/application-pdfName.properties`

Bei der Konvertierung von XJustiz-XML nach PDF vergeben die Werkzeuge einen sprechenden Anzeigenamen (Attribut anzeigename in der Antwort). Welcher Name für welchen Nachrichtentyp verwendet wird, steuert diese Datei. Auslieferungszustand (Auszug):

# UUID im Namen
includeUuid=false

# Fallback
defaultName=sonstiges

# Grunddatensatz (GDS)
nachricht.gds.uebermittlungSchriftgutobjekte.0005005=schriftgutobjekte
nachricht.gds.fehler.0005007=fehlermeldung

So funktioniert die Zuordnung:

Schlüssel ist die Nachricht-Bezeichnung aus der XML-Datei (z. B. nachricht.gds.fehler.0005007), Wert ist der gewünschte PDF-Name.
Ist für eine Nachricht kein Eintrag vorhanden, wird der Wert von defaultName verwendet (fehlt auch dieser, greift der eingebaute Fallback sonstiges).
Steht includeUuid=true, wird an jeden Namen eine UUID angehängt — nützlich, um Namenskollisionen bei Massenverarbeitung zu vermeiden.
Ein Schlüssel ohne Wert ergibt einen leeren Namen — daher Einträge nie halbfertig stehen lassen.

Beispiel: Eigenen Namen für eEB-Nachrichten vergeben

Um erzeugte PDFs zum elektronischen Empfangsbekenntnis als empfangsbekenntnis.pdf zu benennen, eine Zeile ergänzen:

nachricht.gds.zustellung.eeb.zuruecklaufend.0005037=empfangsbekenntnis

Anschließend die Anwendung neu starten.

Alternativ kann beim Start eine ganz andere Konfigurationsdatei angegeben werden:

java -DpdfNameSource=/pfad/zu/eigener-pdfName.properties -jar xjustiz-tools-exec-1.4.0.jar

Datei muss vorhanden sein

Existiert weder die Standarddatei noch eine per -DpdfNameSource angegebene Alternative, schlägt die PDF-Erzeugung mit einem Fehler fehl.

Startseite der Demo-Anwendung: `tools/startseite-config.js`

Die Startseite der Demo-Anwendung (Kachelübersicht der Werkzeuge) ist vollständig über die Datei tools/startseite-config.js konfigurierbar — ohne Eingriff in den Quellcode. Die Datei enthält ein JavaScript-Objekt mit drei Bereichen:

kopf — Titel, Untertitel und Beschreibungstext der Seite
footer — Fußzeile der Seite
kacheln — ein Array mit einer Kachel je Werkzeug

Aufbau einer Kachel

{
  "id": "validate",
  "titel": "XJustiz-Validierung",
  "emoji": "⚖️",
  "sichtbar": true,
  "status": "freigegeben",
  "href": "Tools/SimpleValidate.html",
  "verlauf": ["#009ee3", "#004b76"],
  "beschreibung": "XML-Validator für XJustiz-Dokumente ...",
  "features": ["Schema-Validierung", "Syntax-Highlighting"],
  "cta": "🔍 Jetzt validieren"
}

Feld	Bedeutung
`sichtbar`	`true` = Kachel wird angezeigt, `false` = ausgeblendet
`status`	Badge der Kachel: `freigegeben`, `beta`, `preview` oder `planung` (nicht klickbar)
`href`	Zielseite, die beim Anklicken geöffnet wird
`verlauf`	Zwei Hex-Farben für den Farbverlauf der Vorschau-Kachel
`titel`, `beschreibung`, `features`, `cta`	Frei editierbare Texte (Überschrift, Beschreibung, Featureliste, Button)

Die Reihenfolge der Einträge im Array kacheln bestimmt die Reihenfolge der Kacheln auf der Startseite.

Beispiel: Ein Werkzeug ausblenden

Um z. B. den XDomea-Konverter von der Startseite zu nehmen, in dessen Kachel-Eintrag setzen:

"sichtbar": false,

Danach die Startseite im Browser neu laden — ein Neustart des Servers ist nicht nötig.

Beispiel: Eigene Kachel ergänzen

Die ausgelieferte Konfiguration enthält am Ende eine unsichtbare Beispiel-Kachel ("id": "codelisten", Status planung). Sie kann als Kopiervorlage für eigene Einträge dienen: Eintrag duplizieren, Texte und href anpassen und "sichtbar": true setzen.

Nur Darstellung, keine Funktion

Die Datei steuert ausschließlich die Darstellung der Landingpage. Ein ausgeblendetes Werkzeug bleibt über seine URL und die REST-Schnittstelle weiterhin erreichbar.

Loader-Konfiguration: `tools/loader-config.js`

Beim Start über start_demo.sh / start_demo.bat öffnet sich zunächst die lokale Seite tools/loader.html. Sie zeigt einen Ladebildschirm, prüft in Intervallen, ob der Server bereit ist, und leitet dann automatisch auf die Startseite weiter. Ihr Verhalten steuert die einzeilige Datei tools/loader-config.js:

window.LOADER_CONFIG = { port: '8888', path: '/index.html', tries: 40, interval: 2000 };

Feld	Bedeutung	Standard
`port`	Port, auf dem der Server erwartet wird	`8888`
`path`	Seite, auf die nach erfolgreichem Start weitergeleitet wird	`/index.html`
`tries`	Anzahl der Verbindungsversuche, bevor ein Fehler angezeigt wird	`40`
`interval`	Wartezeit zwischen zwei Versuchen in Millisekunden	`2000`

Mit den Standardwerten wartet der Loader also bis zu 80 Sekunden (40 × 2 s) auf den Server.

Alternativ lassen sich Port und Pfad auch per URL-Parameter übersteuern, ohne die Datei zu ändern:

loader.html?port=9091
loader.html?port=9091&path=/Formulare/index.html

Port muss zum Server passen

Wird der Server-Port in config/application.properties geändert, muss der Loader denselben Port verwenden — entweder in loader-config.js oder per URL-Parameter. Bei Start über start_demo.sh / start_demo.bat zusätzlich die Variable SERVER_PORT im Skript anpassen.

Formularübersicht: `formulare.json`

Die Übersicht der Formularsammlung wird über die Datei formulare.json gesteuert. Sie liegt innerhalb der JAR-Datei unter:

BOOT-INF/classes/static/Formulare/formulare.json

Über die Datei lässt sich festlegen:

Formulare hinzufügen oder entfernen — jedes Formular ist ein Objekt im Bereich Formulare; neue Formulare werden durch einen weiteren Eintrag eingebunden.
Kategorien verwalten — im Bereich Kategorien können Fachgebiete angelegt oder umbenannt werden; die Zuordnung erfolgt je Formular über den Parameter gruppe.
Reihenfolge — die Reihenfolge der Einträge im Array bestimmt die Reihenfolge innerhalb der Kategorie.
Darstellung — Anzeigename, Beschreibung und Emoji sind frei anpassbar.
Status — freigegeben oder beta steuert das Status-Badge in der Übersicht.
Zielseite — der Parameter href legt die HTML-Datei fest, die beim Öffnen geladen wird.
Suche — über tags und suche können zusätzliche Suchbegriffe hinterlegt werden.

Änderung erfordert Eingriff in die JAR

Da die Datei Teil der JAR ist, muss die angepasste Fassung wieder in die JAR unter BOOT-INF/classes/static/Formulare/ übernommen (oder die JAR neu erstellt) und die Anwendung anschließend neu gestartet werden. Diese Anpassung richtet sich daher an technisch versierte Betreiber.

Eigene Prüfregeln: Ordner `schematrons/`

Für die Validierungsoperationen können eigene Schematron-Dateien mit zusätzlichen Prüfregeln je Nachrichtentyp hinterlegt werden — nach XJustiz-Versionen getrennt:

Passenden Versionsordner unterhalb von schematrons/ wählen (z. B. schematrons/3_6_2/).
Die Schematron-Datei (.sch) dort ablegen.

Die Datei nach dem Root-Element des Nachrichtentyps benennen, z. B.:

schematrons/3_6_2/nachricht.zvstr.forderungspfaendung.2600002.sch

Anwendung neu starten.

Bei einer Prüfung wird die verwendete Schematron-Datei in dieser Prioritäten-Reihenfolge ausgewählt:

An der Schnittstelle übergebene Datei(en)
Passende Datei aus dem schematrons/-Ordner
Standard-Datei aus der XJustiz-Spezifikation

Nach Updates erneut einspielen

Nach jeder Aktualisierung der Anwendung müssen eigene Schematron-Dateien erneut in die entsprechenden Versionsordner gelegt werden.

Startparameter

Neben den Konfigurationsdateien werden einige Einstellungen als Java-Startparameter (-D...) übergeben. Sie werden in den Startskripten start.sh / start.bat bzw. start_demo.sh / start_demo.bat gesetzt oder direkt an den java-Aufruf angehängt:

java -DdemoMode=false -jar xjustiz-tools-exec-1.4.0.jar

Demo-Modus

Parameter	Bedeutung
`-DdemoMode` bzw. `-DdemoMode=true`	Startet die Anwendung im Testbetrieb: SSL und CORS sind deaktiviert
`-Dstatic.csp.header=...`	Setzt den Content-Security-Policy-Header für die Demo-Seiten (wird von `start_demo.sh` automatisch auf `http://localhost:<Port>` gesetzt)

Demo-Modus nicht produktiv einsetzen

Im Demo-Modus sind die Sicherheitsfeatures SSL und CORS abgeschaltet. Er ist ausschließlich für Test und Erprobung gedacht — etwa um die Schnittstelle mit einem Swagger-/OpenAPI-Editor und der Datei doc/xjustiz-tools.yaml auszuprobieren.

Codelisten-Aktualisierung

Die Werkzeuge aktualisieren täglich um 2:30 Uhr die intern verwendeten Typ-3-Codelisten aus dem XRepository und speichern sie in einem temporären Verzeichnis.

Parameter	Bedeutung	Beispiel
`-Dcodelist.update.time="HH:mm"`	Uhrzeit der täglichen Aktualisierung ändern	`-Dcodelist.update.time="04:00"`
`-Dcodelist.update.time="-"`	Aktualisierung vollständig abschalten (z. B. für Offline-Betrieb)
`-Dxjustiz.tmp.dir=/pfad`	Zielverzeichnis für die zwischengespeicherten Codelisten ändern (Standard: Ordner `XJustizTools` im Java-Temp-Verzeichnis)	`-Dxjustiz.tmp.dir=/opt/xjustiz/cache`

Proxy

Ist für die Verbindung zum XRepository ein Proxy erforderlich, kann dieser über die üblichen Java-Proxy-Parameter konfiguriert werden:

java -Dhttps.proxyHost=proxy.behoerde.de \
     -Dhttps.proxyPort=3128 \
     -Dhttp.proxyUser=benutzer \
     -Dhttp.proxyPassword=passwort \
     -Dhttp.nonProxyHosts="localhost|*.behoerde.de" \
     -jar xjustiz-tools-exec-1.4.0.jar

PDF-Namenskonfiguration

Parameter	Bedeutung
`-DpdfNameSource=/pfad/zur/datei`	Alternative Datei für die PDF-Namenskonfiguration statt `config/application-pdfName.properties`

Häufige Anpassungen auf einen Blick

Ich möchte …	Dann …
… einen anderen Port verwenden	`server.port` in `config/application.properties` ändern; bei Nutzung der Demo-Startskripte zusätzlich `SERVER_PORT` im Skript und den Port in `tools/loader-config.js` anpassen
… ein eigenes SSL-Zertifikat einbinden	Keystore nach `config/` kopieren und die drei `server.ssl.*`-Parameter anpassen
… größere Dateien hochladen	`spring.servlet.multipart.max-file-size` und `...max-request-size` erhöhen
… ein Werkzeug von der Startseite entfernen	In `tools/startseite-config.js` bei der Kachel `"sichtbar": false` setzen und die Seite neu laden
… Texte oder Farben der Startseite ändern	`kopf`, `footer` bzw. die Kachel-Felder in `tools/startseite-config.js` anpassen
… erzeugten PDFs eigene Namen geben	Eintrag in `config/application-pdfName.properties` ergänzen und die Anwendung neu starten
… eigene Prüfregeln bei der Validierung anwenden	`.sch`-Datei in den passenden Versionsordner unter `schematrons/` legen und die Anwendung neu starten
… die Werkzeuge offline betreiben	Codelisten-Update mit `-Dcodelist.update.time="-"` abschalten und die Codelisten manuell hinterlegen (siehe Technische Rahmenbedingungen)