Knowledge-Base-Sync einrichten und betreiben

Mit dem Knowledge-Base-Sync importiert CompanyWizard externe Quellen wiederkehrend in einen lokalen Vault: ein Verzeichnis auf der Platte, einen Confluence-Space oder einen SharePoint-Ordner. Verwaltet wird das auf der Admin-Seite Administration → Integrationen → Knowledge-Sync.

Das Konzept in fünf Sätzen

1. Bei jedem Lauf zählt der Sync die Quelle auf, vergleicht gegen den letzten Stand (Ledger je Quelle) und importiert nur Neues und Geändertes über die normale Import-Pipeline — Unverändertes wird übersprungen.
2. Aktualisierte Artikel werden an Ort und Stelle überschrieben; ihre Zugriffsrechte (Rollen, Klassifikation) bleiben dabei garantiert erhalten — nur neue Artikel bekommen die RBAC-Standardwerte der Konfiguration.
3. Es gilt die Single-Writer-Regel: der Ziel-Vault muss lokal sein, und pro Vault ist genau eine Sync-Konfiguration erlaubt — das Speichern einer zweiten wird abgelehnt. Zwei Quellen brauchen also zwei Vaults.
4. Synchronisierte Artikel tragen sync_managed: true im Frontmatter; Ansicht und Editor zeigen dazu ein Hinweis-Banner, denn manuelle Änderungen werden beim nächsten Lauf überschrieben. → Synchronisierte Artikel & der Sync-Button
5. Ein Zeitplan (Cron) stößt die Läufe automatisch an; zusätzlich gibt es „Jetzt syncen” und einen Trockenlauf im Admin-Panel sowie den Sync-Button in der Wissensdatenbank.

Voraussetzungen je Quelle

Quelle	Voraussetzung
Verzeichnis	Der Pfad muss für die ausführende Instanz lesbar sein (Server-Pfad im Web-Modus, lokaler Pfad auf dem Desktop).
Confluence	Zugangsdaten als Provider-Eintrag der Kategorie confluence unter KI-Modelle / Provider (Basis-URL + API-Token).
SharePoint	MicrosoftGraph:ClientId konfiguriert + delegierte Graph-Berechtigungen. Web: die Person, der die Konfiguration gehört (Owner), muss ihr Microsoft-Konto verbunden haben — über die Karte „Microsoft-Verbindung für geplante SharePoint-Synchronisierungen” oben im Tab Wissens-Sync. Dieselbe Verbindung trägt auch die Ordnerauswahl; geplante Läufe nutzen sie still im Hintergrund. Desktop: die Anmeldung gilt maschinenweit; die Erst-Anmeldung erfolgt über den Sync-Button in der Wissensdatenbank („Anmelden & synchronisieren”).

Konfiguration anlegen

Unter Administration → Integrationen → Knowledge-Sync eine neue Konfiguration erstellen:

1. Anzeigename und Quelltyp wählen.

2. Quell-Einstellungen (JSON) ausfüllen — Pflichtfelder je Typ:

   Quelltyp	Pflichtfelder	Optional	Beispiel
   directory	rootPath	—	{ "rootPath": "/srv/docs/handbuch" }
   confluence	baseUrl, spaceKey	eigenes CQL-Fragment	{ "baseUrl": "https://firma.atlassian.net/wiki", "spaceKey": "DOCS" }
   sharepoint	driveId	folderId	{ "driveId": "b!Xyz…", "folderId": "01ABC…" }

3. Ziel festlegen: Ziel-Vault (muss lokal sein) und Ziel-Ordner (Standard: imports), dazu den Konverter.

4. RBAC-Standardwerte setzen: Zugriffsrollen, Abteilung und Klassifikation, die neu importierte Artikel erhalten. Bestehende Artikel behalten bei Updates ihre Rechte.

5. AutoPromote entscheiden: eingeschaltet werden Importe ohne manuellen Review-Schritt direkt veröffentlicht; ausgeschaltet landen sie in der Import-Review des Konfigurations-Owners.

6. Löschverhalten wählen (siehe unten), Cron-Zeitplan setzen und die Konfiguration aktivieren.

Beim Speichern wird validiert: fehlende Pflichtfelder, ungültiges JSON, ein nicht-lokaler Ziel-Vault oder ein Vault, der bereits Ziel einer anderen Konfiguration ist, werden mit einer klaren Fehlermeldung abgelehnt.

Betrieb: Läufe starten und Berichte lesen

• Jetzt syncen startet einen Lauf sofort; der Trockenlauf zeigt, was passieren würde (inklusive Listen der betroffenen Artikel), ohne etwas zu schreiben — empfehlenswert vor dem ersten scharfen Lauf und vor dem Aktivieren von AutoPromote oder Löschen.
• Der Bericht je Lauf zählt: Neu / Geändert / Unverändert / Gelöscht / Tombstoned / Hart gelöscht / Promotet / Fehlgeschlagen. Fehlgeschlagene Einzelposten enthalten den Grund; ein Fehler bricht nicht den ganzen Lauf ab.
• „Läuft bereits”: Zeitplan, Admin-Panel und der Sync-Button in der Wissensdatenbank teilen sich eine Sperre pro Konfiguration — es läuft nie zweimal parallel, ein zweiter Start meldet nur den laufenden Sync.
• Schlägt ein Lauf als Ganzes fehl, steht der Grund im Bericht; der Lauf ist isoliert und der Fortschritts-Cursor bleibt unangetastet — der nächste Lauf setzt sauber wieder auf.

Löschverhalten

Was passiert, wenn ein Dokument an der Quelle verschwindet, steuert die Policy:

Policy	Wirkung
Belassen (Standard)	Artikel bleibt unverändert; die Löschung erscheint nur im Bericht.
Tombstone	Artikel wird als archiviert markiert: status: archived + sync_deleted im Frontmatter. Er bleibt auffindbar, gilt aber als veraltet.
Löschen	Artikel wird endgültig entfernt.

Zwei Schutzmechanismen:

• Lösch-Schwellwert-Guard: Würden auf einen Schlag mehr als 50 % von mindestens 4 Artikeln verschwinden, bricht der Lauf ab und nichts wird gelöscht — Schutz vor fehlerhaften Quell-Listings.
• Wiederauftauchen reaktiviert: Taucht das Quelldokument wieder auf, wird ein tombstoned Artikel automatisch reaktiviert — das Tombstone-Frontmatter wird bereinigt, ein manuell gesetzter Status bleibt erhalten.

Status-Werte & Behebung

Status	Ursache	Behebung
Ok	Letzter Lauf erfolgreich.	—
Failed	Lauf mit Fehler beendet (Grund im Bericht).	Grund im Bericht prüfen (Quelle erreichbar? Pfad korrekt?), dann erneut ausführen.
NeedsReauth	SharePoint-Anmeldung abgelaufen oder widerrufen.	Web: der Konfigurations-Owner verbindet sein Microsoft-Konto neu — auf der Karte oben im Tab Wissens-Sync. Eine Verbindung durch einen anderen Admin hilft dem Lauf nicht. Desktop: in der Wissensdatenbank zeigt der Sync-Button „Anmelden & synchronisieren” — Klick öffnet die Microsoft-Anmeldung im System-Browser; danach laufen geplante Syncs wieder still.
Invalid	Konfiguration ungültig geworden (z. B. Ziel-Vault ist nicht mehr lokal).	Konfiguration öffnen, Ziel korrigieren, neu speichern.
Never	Noch nie gelaufen.	Zeitplan prüfen bzw. „Jetzt syncen”.

Desktop-Hinweis

Auf dem Desktop tickt der Zeitplan nur bei geöffneter App — ein Banner auf der Knowledge-Sync-Seite weist darauf hin (nur dort erscheint es). Für kontinuierlichen, unbeaufsichtigten Sync empfiehlt sich der Web-Modus.

Wie es weitergeht

• Synchronisierte Artikel & der Sync-Button — die Endbenutzer-Sicht: Banner, Artikel übernehmen, Button bedienen
• Vault anlegen und Rechte vergeben
• Ein Dokument importieren und freigeben