XRechnung-Addon für Alfresco – Installations- & Nutzungshandbuch

Das XRechnung-Addon von LNSolutions erweitert Alfresco um vollständige Unterstützung für deutsche XRechnung-E-Rechnungen. Es erkennt XRechnung-XML-Dokumente automatisch, reichert sie mit Metadaten an und erzeugt hochwertige HTML- und PDF-Renderings über eine dedizierte Transform Engine (T‑Engine).

1. Komponenten & Download-Links

Die Lösung besteht aus drei Hauptkomponenten:

Lizenzmodul (verpflichtend)
Stellt die Lizenzvalidierung für alle LNSolutions-Addons bereit.
Download: lnsolutions-alfresco-license-1.0.0.jar
XRechnung-Platform-Addon (verpflichtend)
Alfresco-Repository-Erweiterung für XRechnung-Erkennung, Metadatenaspekt xr:xrechnungMetadata und Integration mit der T‑Engine.
Download: xrechnung-lnsolutions-platform-1.0.jar
XRechnung T‑Engine (verpflichtend für HTML/PDF)
Eigenständiger Spring-Boot-Mikroservice, der XRechnung-XML in HTML transformiert und die PDF-Pipeline von Alfresco versorgt.
JAR-Download: xrechnung-tengine-1.0.jar
oder Docker-Image: xrechnung-tengine:latest

2. Voraussetzungen

Alfresco Content Services 7.x+ (Repository)
Java 11+ auf Alfresco- und T‑Engine-Seite
Zugriff zum Bereitstellen von JARs (Tomcat WEB-INF/lib oder eigenes Docker-Image)
Gültiger LNSolutions-Lizenzschlüssel (oder Testlizenz)

Um eine Testlizenz anzufordern, verwenden Sie:
XRechnung-Testlizenz anfordern

3. Installation des Lizenzmoduls

Alfresco stoppen.
lnsolutions-alfresco-license-1.0.0.jar kopieren nach:
- <TOMCAT>/webapps/alfresco/WEB-INF/lib/ (ohne Docker)
- oder in Ihr eigenes Alfresco-Docker-Image einbinden.
Alfresco starten und prüfen, ob das Lizenzmodul geladen wurde (Logs prüfen).
Installieren oder laden Sie Ihren Lizenzschlüssel hoch, indem Sie den Schlüssel xrechnung.license.public.key in Ihrer Datei alfresco-global.properties verwenden.

4. Installation des XRechnung-Platform-Addons

Alfresco stoppen.
xrechnung-lnsolutions-platform-1.0-SNAPSHOT.jar kopieren nach:
- <TOMCAT>/webapps/alfresco/WEB-INF/lib/ (ohne Docker)
- oder in Ihr eigenes Alfresco-Docker-Image.
Sicherstellen, dass das Lizenzmodul vor diesem Modul geladen wird (das XRechnung-Modul deklariert eine Abhängigkeit von lnsolutions-alfresco-license).
Alfresco starten und die Logs auf die Initialisierung des XRechnung-Moduls prüfen.

4.1. Alfresco-Konfiguration

Fügen Sie in alfresco-global.properties (oder der entsprechenden Docker-Umgebung) die URL der XRechnung-T‑Engine hinzu:

# URL der XRechnung Transform Engine
localTransform.xrechnung.url=http://xrechnung-tengine:8091

Passen Sie Host/Port an Ihre Umgebung an (z. B. http://localhost:8091 für lokale Tests).

5. Bereitstellung der XRechnung T‑Engine

5.1. Ausführung als Docker-Container (empfohlen)

Docker-Image laden oder bauen:

docker run -d -p 8091:8091 --name xrechnung-tengine xrechnung-tengine:latest

Prüfen, ob der Dienst läuft:
```
curl http://localhost:8091/ready
```

5.2. Ausführung als eigenständige JAR

Dienst starten:

java -jar xrechnung-tengine-1.0-SNAPSHOT.jar

Bereitschaft prüfen:
```
curl http://localhost:8091/ready
```

5.3. T‑Engine-Konfiguration (Lizenz & Kern-Transform)

Konfigurieren Sie für die T‑Engine die folgenden Umgebungsvariablen (z. B. in einer .env-Datei oder der Service-Konfiguration):

XRECHNUNG_TRANSFORM_CONFIG=/opt/xrechnung-tengine/config/xrechnung-transform-config.json
CORE_AIO_TRANSFORM_URL=http://transform-core-aio:8090/transform
LICENSE_VALIDATION_URL=http://<alfresco-host>:8080/alfresco/service/lnsolutions/admin/license-status

Die T‑Engine ruft LICENSE_VALIDATION_URL vor jeder Transformation auf, um Ihre Lizenz über Alfresco zu prüfen.

6. Verwendung des XRechnung-Addons

6.1. Automatische Erkennung & Metadaten

Melden Sie sich in Alfresco als Administrator oder Benutzer an.
Laden Sie eine XRechnung-XML-Rechnung (UBL oder CII) in einen beliebigen Ordner hoch.
Das XRechnungDetectionBehavior prüft den Inhalt und wendet bei gültigen Dokumenten automatisch den XRechnung-Metadatenaspekt (xr:xrechnungMetadata) an.
In den Dokumenteigenschaften sehen Sie XRechnung-spezifische Felder wie: Digital Invoice Profile, Digital Invoice Profile Description (Short) und Is Digital Invoice.

6.2. HTML-Vorschau

Öffnen Sie die Dokumentdetailseite in Alfresco.
Verwenden Sie die integrierte Vorschau: Alfresco fordert eine HTML-Rendition von der XRechnung-T‑Engine an und zeigt eine übersichtlich formatierte Rechnung an.

Für technische Tests können Sie außerdem das Web Script aufrufen:

http://<alfresco-host>:8080/alfresco/service/lnsolutions/node/xrechnung-html?id={nodeId}

6.3. PDF-Renderings

Das Addon unterstützt außerdem eine PDF-Pipeline: XRechnung XML → HTML (T‑Engine) → PDF (Alfresco pdfRenderer).

Laden Sie ein XRechnung-XML-Dokument hoch.
Warten Sie, bis Alfresco die Renderings erzeugt hat.
Laden Sie das PDF-Rendering von der Dokumentdetailseite herunter und prüfen Sie, ob Layout und Zeichen (z. B. Umlaute) korrekt sind.

7. XRechnung-Indikator & Verhalten

Das XRechnung-Addon verwendet den XRechnung-Metadatenaspekt (xr:xrechnungMetadata) als technischen Indikator dafür, dass ein Dokument eine gültige XRechnung ist.

Is Digital Invoice (xr:isDigitalInvoice): Boolescher Schalter, der gesetzt wird, wenn ein Dokument als XRechnung erkannt wurde.
Digital Invoice Profile (xr:digitalInvoiceProfile): Speichert den erkannten Digital-Invoice-Profilbezeichner.
Digital Invoice Profile Description (Short) (xr:digitalInvoiceProfileDescShort): Kurze, menschenlesbare Bezeichnung für das erkannte Profil (z. B. in Alfresco als „Digital Invoice Profile Description (Short)“ angezeigt).

Das XRechnungDetectionBehavior lauscht auf das Anlegen und Aktualisieren von cm:content-Knoten. Wenn eine hochgeladene XML-Datei den XRechnung-Mustern entspricht (basierend auf Inhalt, Metadaten oder Dateinamen), fügt das Behavior automatisch den Aspekt xr:xrechnungMetadata hinzu und setzt xr:isDigitalInvoice = true.

Nur Dokumente, die diesen XRechnung-Indikator tragen (den Aspekt xr:xrechnungMetadata mit xr:isDigitalInvoice=true), werden von der HTML/PDF-Transformationspipeline als XRechnung behandelt. Allgemeine XML-Dateien bleiben unberührt, bis sie eindeutig als XRechnung identifiziert wurden.

8. Anfordern einer Testlizenz

Wenn Sie das XRechnung-Addon vor dem Erwerb einer Volllizenz evaluieren möchten, fordern Sie hier eine Testlizenz an:

XRechnung-Testlizenz anfordern

Oder kontaktieren Sie uns für eine dauerhafte Lizenz.

XRechnung für Alfresco