Zum Inhalt

Übersicht

Repository

Repository Issues

Allgemeine Informationen

Kurzbeschreibung des Add-ins

Behörden-KlarText ermöglicht es, Texte mithilfe von Large Language Models (LLMs) zu optimieren. Bei diesem Add-In handelt es sich um eine Implementierung, die es ermöglicht, markierten Text durch eine Schnittstelle in besser verständlichen und klareren Text zu überführen.

Welche Probleme löst es?

Viele Dokumente des täglichen Bedarfes (Verträge, Kommunikation mit Behörden usw.) beinhalten oft schwer verständlichen Text. Diese Software ermöglicht die Vereinfachung solcher Textblöcke in verständliche Sprache.

Für welche Office-App ist es gedacht?

Dieses Add-in ist für Outlook Web und Desktop Installationen von Microsoft 365 entwickelt worden.

Beachten Sie hierbei bitte die Lizenzbestimmungen der Office JavaScript API.

Kompatibilität

Prinzipiell sollte es auch mit Microsoft Office 2016 (und neuer) kompatibel sein. An dieser Stelle sei darauf hingewiesen dass ältere Versionen, welche auf Internet Explorer oder EdgeHTML (Edge Legacy) basieren, nicht unterstützt werden:

Fluent UI React v. 9 uses modern JavaScript syntax that is not supported in Trident (Internet Explorer) or EdgeHTML (Edge Legacy), so this add-in won't work in Office versions that use these webviews. The script below makes the following div display when an unsupported webview is in use, and hides the React container div.

Einschätzung

IE und Edge Legacy sind so gut wie nicht mehr in Verwendung, eine Benutzung dieser stark-veralteten Browser wäre sowieso grob fahrlässig. Die Desktop-Anwendungen nutzen WebView2, welches auf modernen Edge-Standards basiert.

Beschränkungen

  • Leider funktionieren Shortcuts in Outlook Web-Add-Ins nicht (auch nicht in der Desktop-Version)
  • Des weiteren lässt sich das Addon nur im E-Mail-Verfassen verwenden. Nicht im Lesemodus

Bauen

Überblick

Das Web-Add-In wird als Container ausgeliefert. Da Microsoft Office Add-Ins zwingend HTTPS voraussetzen, muss für eine Integration in Word eine SSL-gesicherte URL bereitgestellt werden. Im Folgenden wird für Testzwecke das Deployment mit Docker und einem selbst erstellten Zertifikat beschrieben.

1. Container bauen

Erstellen Sie das Docker-Image für das Web-Add-In:

docker build -t behoerden-klartext/outlook-web-add-in .

2. Zertifikate für lokale Entwicklung (WSL2, Windows)

Schritt A: Zertifikate in WSL2 oder Linux erstellen

Verwenden Sie mkcert, um Zertifikate zu erstellen, und stellen Sie sicher, dass der Key für Docker lesbar ist:

apt install mkcert
mkdir -p certs
mkcert -key-file certs/localhost.key -cert-file certs/localhost.crt localhost 127.0.0.1 ::1
chmod 644 certs/localhost.key

Schritt B: Zertifikat unter Windows vertrauen

Falls das Add-In nicht korrekt geladen wird, müssen Sie möglicherweise das Zertifikat unter Windows als vertrauenswürdig hinzufügen. Dies ist erforderlich, wenn Sie Word unter Windows verwenden (nicht im Webbrowser) und die in WSL2 erstellte "Certification Authority" (CA) noch nicht von Windows akzeptiert wird.

  1. CA-Pfad finden: 
    mkcert -CAROOT
  2. Ordner in Windows öffnen: Navigieren Sie im Windows-Explorer zu dem ausgegebenen Pfad (z. B. \\wsl$\Ubuntu\home\username\.local\share\mkcert).
  3. Zertifikat installieren:
  4. Kopieren Sie rootCA.pem auf Ihren Windows-Desktop und benennen Sie die Datei in rootCA.crt um.
  5. Doppelklick auf rootCA.crt -> Zertifikat installieren...
  6. Wählen Sie Aktueller Benutzer -> Weiter.
  7. Wählen Sie Alle Zertifikate in folgendem Speicher speichern.
  8. Klicken Sie auf Durchsuchen... und wählen Sie Vertrauenswürdige Stammzertifizierungsstellen.
  9. Klicken Sie auf OK -> Weiter -> Fertig stellen.

3. Container starten

Starten Sie den Container mit eingebundenen Zertifikaten und aktivierter SSL-Unterstützung. Der Container benötigt Zugriff auf das Backend (hier über das externe Netzwerk behoerden_klartext_net).

docker run --rm -p 9999:9999 \
  -e ADDIN_URL=https://localhost:9999 \
  -e USE_SSL=true \
  -v $(pwd)/certs:/etc/nginx/certs:ro \
  --network behoerden_klartext_net \
  behoerden-klartext/outlook-web-add-in

Optional kann auch ein Titel mit angegeben werden, der die gesamte Anwendung umbenennt: 

docker run --rm -p 9999:9999 \
  -e ADDIN_URL=https://localhost:9999 \
  -e USE_SSL=true \
  -e TITLE="Custom App Name" \
  -v $(pwd)/certs:/etc/nginx/certs:ro \
  --network behoerden_klartext_net \
  behoerden-klartext/outlook-web-add-in

Sollte das ADD_IN in einer On-Premise-Instanz von Outlook/Microsoft Office laufen, muss die Environment Variable ORIGIN_URL gesetzt werden. Damit wird gestattet, dass dieser Host das Add-In im iFrame einbetten darf. Folgende Werte sind zulässig: * https://example.com * https://www.example.com * https://example1.com https://example2.com https://example3.com

Bitte bei der Wertzuweisung keine Anführungszeichen verwenden!

Per Default sind folgende Origins gesetzt: * https://*.office.com * https://*.microsoft.com * https://outlook.live.com * *.officeapps.live.com * ms-appx-web: ms-word: wss: (für die Desktop-Anwendungen)

4. Konfiguration & Umgebungsvariablen

Das Verhalten des Containers wird über Umgebungsvariablen gesteuert:

Variable Beschreibung Wichtig
ADDIN_URL Die externe Basis-URL des Add-Ins. Muss auf die externe HTTPS-URL zeigen (z.B. https://localhost:9999). Diese URL wird beim Start in die manifest.xml geschrieben.
USE_SSL Aktiviert den SSL-Modus im Nginx. Setzen Sie true, um HTTPS zu aktivieren.
ORIGIN_URL Optional: konfiguriert weitere Origins
TITLE Optional: Damit lässt sich der Titel der Anwendung ganz leicht austauschen. Default: "Behörden KlarText"
UPSTREAM (Optional) Sollte ein anderes Backend genutzt werden kann über diese Env der Host gesetzt werden. Mögliche Werte: z.B. example-server.com
UPSTREAM_PORT (Optional) Sollte ein anderes Backend genutzt werden kann über diese Env der Port gesetzt werden. 443 für https, 80 für http oder ein anderer Port
UPSTREAM_PROTOCOL (Optional) Sollte ein anderes Backend genutzt werden kann über diese Env das Protokoll gesetzt werden. Zugelassene Werte https oder http
UPSTREAM_BASE_PATH (Optional) Sollte ein anderes Backend genutzt werden kann über diese Env der Pfad gesetzt werden, wenn das Backend nicht über die Root-URI erreichbar ist z.B. /custom für Backend-URI example-server.com/custom. Wichtig: muss mit / beginnen und darf nicht mit einem Slash enden!

Hinweise:

  • Der nginx im Container erwartet das Backend unter http://backend:8000 (Container-interner Hostname).\ Falls das Backend anders konfiguriert werden soll, können die UPSTREAM-Envs genutzt werden.
  • Das Manifest ist nach dem Start unter <ADDIN_URL>/manifest.xml abrufbar. Laden Sie es für das Test-Deployment herunter.
  • In der aktuellen SSL-Nginx-Konfiguration wird Streaming gepuffert. Dies kann dazu führen, dass Echtzeit-Streaming nicht korrekt funktioniert und der optimierte Text als Ganzes angezeigt wird. Dadurch kann es etwas dauern, bis die Antwort angezeigt wird.

5. Bereitstellung in Microsoft 365

Für den produktiven Einsatz oder weitreichende Tests kann das Add-In im Microsoft 365 Admin Center registriert werden. Das Manifest kann dort:

  • direkt als Datei hochgeladen werden,
  • oder per HTTPS-URL referenziert werden (z. B. https://mein-server.de/manifest.xml).

6. Sideloading (optional)

Sideloading ist für schnelle lokale Tests gedacht. Microsoft empfiehlt es nicht für produktive Rollouts.

Diese Methode kann direkt in Word im Browser durchgeführt werden. Es wurde mit Microsoft Edge getestet. Weitere Informationen finden Sie unter Microsoft-Dokumentation.

  1. Öffnen Sie Word in ihrem Browser und ein Dokument.
  2. Wählen Sie Start > Add-ins und dann Weitere Einstellungen oder Weitere Add-Ins.
  3. Im Dialogfeld "Office-Add-ins" wählen Sie Mein Add-in hochladen.
  4. Navigieren Sie zur Manifestdatei des Add-ins und wählen Sie Hochladen.
  5. Das Add-In sollte jetzt im Menüband erscheinen.

Hinweis: diese Installationshinweise funktionieren ebenfalls für die Desktop-Version von Outlook.

pre-commit

Die CI-Pipeline führt bei jedem Push den Job "pre-commit" mit den in .pre-commit-config.yaml hinterlegten Hooks durch. Um ein Failen des Jobs und unnötige Commits zu vermeiden, sollte man pre-commit lokal installieren. So werden etwaige Fehler, die durch Linter und Formatter entdeckt werden, bereits vor dem push offenbart. Dafür muss pip installiert sein. Führen Sie folgende Befehle einmalig in der Konsole aus:

pip install pre-commit
pre-commit install

Wie der Name vermuten lässt, wird der Check vor jedem Commit ausgeführt, bevor Fehler in das Repository gelangen können.

Für das Frontend wird Biome als Linter und Formatter in den pre-commit hooks verwendet. (Hier)[https://biomejs.dev/reference/cli/] sind einige nützliche Befehle zu finden.

Entwicklung

Vorraussetzungen

  • Node.js >= 20
  • Office365 Subscription/Lizenz

Einrichtung

  • Repository klonen
  • npm install
  • Passen Sie ggf. die Konfigurations-Variablen in src/environment/environment.ts an (Sie können ebenfalls eine eigene environment anlegen, z.B. "environment.stage.ts". Über das Webpack FileReplacement-Plugin lassen sich diese Dateien zu Compile-Zeit ersetzen; je nachdem welche Konfiguration Sie bevorzugen)
  • Starten des DEV-Servers via npm start dev-server
  • Manifest.xml bei Outlook hochladen (siehe Bereitstellung)

Hinweis: ggf. müssen Sie unter Linux die Zertifikate selber erzeugen. Eine ausführliche Anleitung finden Sie hier.

Lizenzinformationen

Rechtlicher Hinweis zu Drittanbieter-Komponenten (Microsoft Office.js)

Dieser Quellcode ("Behörden-KlarText") interagiert mit der proprietären Microsoft Office JavaScript API (Office.js).

Technische Einbindung

Das Add-In verweist an mehreren Stellen (insbesondere in HTML-Dateien via <script>-Tags) auf externe Ressourcen der Microsoft Corporation. Die Bibliothek office.js ist nicht physischer Bestandteil dieses Repositories und wird nicht mit diesem Quellcode verteilt oder vervielfältigt.

Die Interaktion erfolgt ausschließlich zur Laufzeit, indem der Client (Browser) des Anwenders die Bibliothek von den Microsoft-Servern (Content Delivery Network - CDN) nachlädt: https://appsforoffice.microsoft.com/lib/1/hosted/office.js

Lizenzbedingungen der Drittkomponente

Die office.js-Bibliothek unterliegt nicht der für dieses Projekt verwendeten Open-Source-Lizenz (Apache License 2.0).

Für die Nutzung, das Laden und die Interaktion mit der office.js-Bibliothek gelten ausschließlich die Microsoft API License Terms. Durch die Nutzung dieses Add-ins akzeptieren Sie neben der Apache-Lizenz für den eigenen Code auch die Bedingungen von Microsoft für die API-Nutzung.

Weitere Informationen: Microsoft API License Terms (Office.js)

Abgrenzung

Wir stellen hiermit klar, dass der in diesem Repository veröffentlichte Code als eigenständiges Werk zu betrachten ist, welches lediglich Schnittstellen zu proprietären Diensten definiert. Es wird kein Eigentum an Microsoft-Code beansprucht oder gewährt.