Confluence-Synchronisation

Diese Anleitung beschreibt, wie Sie eine Verbindung zwischen Ihrem Smartchat-Space und einer Confluence Data Center Instanz einrichten. Nach erfolgreicher Einrichtung synchronisiert Smartchat die Confluence-Seiten automatisch, sodass diese durchsuchbar sind und als Kontext für Ihre Unterhaltungen zur Verfügung stehen.

Hinweis

Diese Funktion ist für Confluence Data Center 9.2.x konzipiert. Andere Versionen funktionieren möglicherweise, sind jedoch nicht offiziell getestet. Confluence Cloud wird derzeit nicht unterstützt.

Weitere Informationen zu dieser Version finden Sie in der Atlassian Confluence Data Center 9.2 Dokumentation.

Voraussetzungen

• Sie benötigen die Rolle Space Owner im Smartchat-Space.
• Ein Service-Account-Token oder Personal Access Token (PAT) vom Confluence-Server, den Sie synchronisieren möchten. Wenden Sie sich an Ihren Confluence-Administrator, falls Sie unsicher sind, wie Sie ein Token erhalten.

Welche Inhalte werden synchronisiert?

Der Synchronisierungsprozess hat Zugriff auf alle Seiten, die für das angegebene Benutzerkonto sichtbar sind. Seiten, die der Benutzer nicht sehen kann, werden nicht synchronisiert — aber es werden alle Seiten synchronisiert, die der Benutzer sehen kann, einschließlich solcher, die als vertraulich oder sensibel gelten könnten.

Stellen Sie vor dem Fortfahren sicher, dass Sie berechtigt sind, all diese Inhalte mit allen Mitgliedern des Smartchat-Spaces zu teilen.

Schritt 1 — Admin Panel öffnen

Öffnen Sie das Smartchat Admin Panel und wählen Sie über das Space-Auswahlmenü oben rechts den gewünschten Space aus.

Schritt 2 — Zu Data Connections navigieren

Klicken Sie in der linken Seitenleiste unter Manage auf Data Connections. Sie sehen eine Tabelle mit allen vorhandenen Verbindungen für diesen Space (anfangs leer).

Schritt 3 — Neue Verbindung erstellen

Klicken Sie oben rechts auf die Schaltfläche + Create connection. Ein Formular mit den folgenden Feldern wird angezeigt:

Füllen Sie die Felder wie folgt aus:

Feld	Beschreibung
Connection Type	Wählen Sie Confluence.
Name	Ein Name für Ihre Verbindung (keine Leerzeichen oder Sonderzeichen erlaubt).
URL	Die Basis-URL Ihrer Confluence-Instanz, z. B. https://strive.devops.t-systems.net/confluence/
Key	Der Confluence Space Key zur Synchronisation. Dies ist das Kürzel, das in Confluence-URLs erscheint. Wenn Ihre Seiten z. B. URLs wie https://strive.devops.t-systems.net/confluence/spaces/AIFS/pages/... haben, lautet der Space Key AIFS.
Credential Type	Wählen Sie Basic Auth.
Credential Authorization	Wählen Sie Read.
Username	Der Benutzername des Service-Accounts oder persönlichen Kontos.
Secret	Das zugehörige Passwort oder der Access Token.

Klicken Sie anschließend auf Save.

Telekom Wiki (wiki.telekom.de)

Wenn Sie eine Verbindung zum internen Telekom Wiki herstellen, verwenden Sie diese Werte:

• URL: https://wiki.telekom.de/ (nicht mehr — kein /wiki, kein Pfad)
• Credential Type: Basic Auth
• Username: Ihr Telekom-Wiki-Benutzername — dieser ist case-sensitive; verwenden Sie für Telekom Wiki Ihre E-Mail-Adresse in Kleinbuchstaben
• Secret: ein API-Token, das Sie unter wiki.telekom.de → API-Tokens generieren

Verwenden Sie nicht Ihr echtes Passwort

Obwohl der Credential Type Basic Auth lautet, müssen Sie das generierte API-Token in das Feld Secret eintragen — nicht Ihr echtes Kontopasswort. „Basic Auth” bedeutet hier „Benutzername und Token als HTTP-Basic-Credentials senden”, nicht „Ihr Login-Passwort senden”.

Schritt 4 — Datenschutzhinweis akzeptieren

Es erscheint ein Hinweisdialog, der Sie darauf aufmerksam macht, dass alle für den angegebenen Confluence-Benutzer sichtbaren Inhalte in den Smartchat-Space übernommen werden und für alle Space-Mitglieder zugänglich sind.

Lesen Sie die Meldung sorgfältig durch. Klicken Sie nur auf Continue, wenn Sie berechtigt sind, alle Confluence-Inhalte mit allen Mitgliedern des Smartchat-Spaces zu teilen.

Schritt 5 — Verbindung überprüfen

Nach dem Akzeptieren des Hinweises wird die Verbindung in der Data-Connections-Tabelle angezeigt. Wenn die Anmeldedaten und die URL korrekt sind, sehen Sie ein grünes WORKS-Badge in der Spalte Test Result.

Synchronisierungszeitplan

• Die Spalte Next Sync zeigt an, wann die nächste Synchronisation geplant ist. Die Synchronisation läuft automatisch täglich um 00:00 Uhr (Mitternacht).
• Die erste Synchronisation importiert alle Seiten und kann je nach Umfang der Inhalte zwischen wenigen Minuten und mehreren Stunden dauern.
• Nachfolgende Synchronisationen verarbeiten nur Änderungen und sind in der Regel deutlich schneller.

Verbindungen verwalten

Jede Verbindung verfügt über eine Reihe von Aktionsschaltflächen auf der rechten Seite der Tabelle:

Schaltfläche	Aktion
Stecker-Symbol	Testen — Überprüft, ob die Anmeldedaten und die URL noch gültig sind.
Play-Symbol	Jetzt synchronisieren — Löst eine sofortige Synchronisation aus. Dies ist nützlich, wenn die nächste geplante Synchronisation zu weit entfernt ist und Sie aktuelle Daten benötigen. Im Normalfall reicht die tägliche automatische Synchronisation aus.
Stift-Symbol	Bearbeiten — Ermöglicht das Ändern von Name, URL, Anmeldedaten oder anderen Einstellungen.
Papierkorb-Symbol	Entfernen — Löscht die Verbindungskonfiguration. Hinweis: Das Entfernen einer Verbindung löscht nicht die bereits synchronisierten Daten.

Synchronisierungsstatus prüfen

Space Owner können den Fortschritt der Synchronisation im Bereich Context Files des Spaces überwachen. Achten Sie auf Dateinamen im Format confluence-YYmDkHEk.html. Jede Datei zeigt eine Status-Spalte an: Ingested bedeutet, dass die Seite erfolgreich verarbeitet wurde. Jeder andere Status weist auf einen Fehler hin — siehe Abschnitt Fehlerbehebung weiter unten.

Zugriff auf die Daten

Achtung

Mit dem v3-Update werden Daten nicht mehr automatisch als Kontext geladen. Die Kollektion „{Space Name} - General” muss zuerst ausgewählt werden.

1. Wählen Sie den Space über den Space Selector oben links aus.
2. Fügen Sie die Kollektion „{Space Name} - General” mit dem #-Shortcut zum Chat hinzu.

Fehlerbehebung

Der Verbindungstest zeigt einen der folgenden Statuscodes an:

Status	Bedeutung
Works	Die Verbindung ist funktionsfähig.
Connection Error	Smartchat kann den Server nicht erreichen (Timeout, DNS-Fehler, Verbindung abgelehnt).
Missing Credentials	Kein Benutzername oder Secret wurde angegeben.
Auth Failed	Die Anmeldedaten wurden abgelehnt (falscher Benutzername/falsches Passwort oder abgelaufener Token).
HTTP 400	Die Anfrage ist fehlerhaft (meist ein falscher URL-Pfad oder fehlende Parameter).
HTTP 404	Die URL oder der Space Key wurde auf dem Server nicht gefunden.
HTTP 4xx	Ein anderer clientseitiger Fehler (z. B. 403 Forbidden, 429 Rate Limited).
HTTP 500	Interner Serverfehler auf Confluence-Seite.
HTTP 5xx	Ein anderer serverseitiger Fehler auf Confluence-Seite.
HTTP Error	Ein nicht klassifizierter HTTP-Fehler.
Failed	Ein unerwarteter Fehler ist aufgetreten.

Connection Error

Ursache: Der Confluence-Server ist nicht erreichbar. Die URL ist möglicherweise falsch, der Server ist nicht verfügbar oder es liegt ein Netzwerk-/Firewall-Problem vor.

Lösung: Überprüfen Sie die korrekte Confluence-Basis-URL. Data-Center-Instanzen verwenden typischerweise einen Pfad wie <https://your-server.example.com/confluence/>. Stellen Sie sicher, dass Sie die API-Basis-URL verwenden und nicht die URL, die Sie im Browser beim Navigieren sehen.

Auth Failed

Ursache: Der Benutzername oder das Passwort ist falsch, oder der API-Token ist abgelaufen oder wurde widerrufen.

Lösung: Erstellen Sie den API-Token in Ihren Confluence-Kontoeinstellungen neu und überprüfen Sie, ob der Benutzername mit dem Token-Inhaber übereinstimmt.

HTTP 404

Ursache: Entweder ist der URL-Pfad falsch (z. B. mit oder ohne /wiki), oder der Space Key ist falsch. Möglicherweise wurde der Anzeigename anstelle des Space Keys verwendet, oder es liegt ein Tippfehler vor. Space Keys unterscheiden zwischen Groß- und Kleinschreibung.

Lösung: Überprüfen Sie zunächst den URL-Pfad. Schlagen Sie anschließend den korrekten Space Key in Confluence unter Settings → Space details nach.

Einrichtung erfolgreich, aber Ingestion oder Chat schlägt fehl

Ursache: Die Smartchat-Space-Konfiguration ist unvollständig (kein API-Key oder Standard-Modell gesetzt). Alternativ drosselt Confluence möglicherweise die API mit einer 429-Antwort, weil zu viele Seiten gleichzeitig abgefragt werden.

Lösung: Stellen Sie sicher, dass der Smartchat-Space über einen gültigen API-Key, ein Embedding-Modell und ein Standard-LLM verfügt, bevor Sie die Confluence-Synchronisation einrichten. Siehe Einen neuen Space einrichten. Bei Ratenbegrenzung reduzieren Sie die Batch-Größe oder wenden Sie sich an Ihren Confluence-Administrator bezüglich der Ratenbegrenzungseinstellungen. Sie können den Ingestion-Status im Bereich Context Files des Spaces überwachen.

Einige oder alle Seiten fehlen nach der Ingestion

Ursache: Der Inhaber des API-Tokens hat keinen Zugriff auf den Confluence-Space, oder einzelne Seiten haben eingeschränkte Berechtigungen, die den Token-Inhaber ausschließen.

Lösung: Stellen Sie sicher, dass der Token-Inhaber Lesezugriff auf den Ziel-Confluence-Space und alle darin enthaltenen Seiten hat. Wenden Sie sich an Ihren Confluence-Administrator, falls seitenbezogene Einschränkungen bestehen.

Geplante Verbesserungen

Die folgenden Verbesserungen sind für kommende Versionen des Smartchat geplant:

• Lesbare Dateinamen in Context Files — Confluence-Seitennamen werden anstelle von gehashten Dateinamen angezeigt (z. B. confluence-YYmDkHEk.html), um die Zuordnung der synchronisierten Seiten zu erleichtern.
• Detaillierte Ingestion-Fehler — Der Bereich Context Files zeigt die genaue Fehlermeldung für fehlgeschlagene Seiten an, sodass Probleme mit dem Abschnitt Fehlerbehebung abgeglichen werden können.