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:

  1. Lizenzmodul (verpflichtend)
    Stellt die Lizenzvalidierung für alle LNSolutions-Addons bereit.
    Download:  lnsolutions-alfresco-license-1.0.0.jar
  2. 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
  3. 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

  1. Alfresco stoppen.
  2. 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.
  3. Alfresco starten und prüfen, ob das Lizenzmodul geladen wurde (Logs prüfen).
  4. 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

  1. Alfresco stoppen.
  2. xrechnung-lnsolutions-platform-1.0-SNAPSHOT.jar kopieren nach:
    • <TOMCAT>/webapps/alfresco/WEB-INF/lib/ (ohne Docker)
    • oder in Ihr eigenes Alfresco-Docker-Image.
  3. Sicherstellen, dass das Lizenzmodul vor diesem Modul geladen wird (das XRechnung-Modul deklariert eine Abhängigkeit von lnsolutions-alfresco-license).
  4. 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)

  1. Docker-Image laden oder bauen: 
    docker run -d -p 8091:8091 --name xrechnung-tengine xrechnung-tengine:latest
  2. Prüfen, ob der Dienst läuft: 
    curl http://localhost:8091/ready

5.2. Ausführung als eigenständige JAR

  1. Dienst starten: 
    java -jar xrechnung-tengine-1.0-SNAPSHOT.jar
  2. 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

  1. Melden Sie sich in Alfresco als Administrator oder Benutzer an.
  2. Laden Sie eine XRechnung-XML-Rechnung (UBL oder CII) in einen beliebigen Ordner hoch.
  3. Das XRechnungDetectionBehavior prüft den Inhalt und wendet bei gültigen Dokumenten automatisch den XRechnung-Metadatenaspekt (xr:xrechnungMetadata) an.
  4. 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

  1. Öffnen Sie die Dokumentdetailseite in Alfresco.
  2. Verwenden Sie die integrierte Vorschau: Alfresco fordert eine HTML-Rendition von der XRechnung-T‑Engine an und zeigt eine übersichtlich formatierte Rechnung an.
  3. 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).

  1. Laden Sie ein XRechnung-XML-Dokument hoch.
  2. Warten Sie, bis Alfresco die Renderings erzeugt hat.
  3. 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.