Set up and operate knowledge-base sync

With knowledge-base sync, CompanyWizard recurringly imports external sources into a local vault: a directory on disk, a Confluence space or a SharePoint folder. It is managed on the admin page Administration → Integrations → Knowledge sync.

The concept in five sentences

1. On every run the sync enumerates the source, diffs it against the last known state (a ledger per source) and imports only new and changed items through the normal import pipeline — unchanged items are skipped.
2. Updated articles are overwritten in place; their access rights (roles, classification) are guaranteed to be preserved — only new articles receive the configuration’s RBAC defaults.
3. The single-writer rule applies: the target vault must be local, and each vault may be the target of exactly one sync configuration — saving a second one is rejected. Two sources therefore need two vaults.
4. Synced articles carry sync_managed: true in their frontmatter; the article view and editor show a notice banner, because manual edits are overwritten on the next run. → Synced articles & the sync button
5. A schedule (cron) triggers runs automatically; in addition there is “Sync now” and a dry run on the admin panel, plus the sync button in the knowledge base.

Prerequisites per source

Source	Prerequisite
Directory	The path must be readable by the executing instance (a server path in web mode, a local path on the desktop).
Confluence	Credentials as a provider entry of category confluence under AI models / providers (base URL + API token).
SharePoint	MicrosoftGraph:ClientId configured + delegated Graph permissions. Web: the person who owns the configuration must have connected their Microsoft account — via the “Microsoft connection for scheduled SharePoint syncs” card at the top of the Knowledge sync tab. The same connection also drives the folder picker; scheduled runs use it silently in the background. Desktop: the sign-in is machine-wide; the initial sign-in happens via the sync button in the knowledge base (“Sign in & sync”).

Creating a configuration

Under Administration → Integrations → Knowledge sync, create a new configuration:

1. Choose a display name and the source type.

2. Fill in the source settings (JSON) — required fields per type:

   Source type	Required	Optional	Example
   directory	rootPath	—	{ "rootPath": "/srv/docs/handbook" }
   confluence	baseUrl, spaceKey	custom CQL fragment	{ "baseUrl": "https://company.atlassian.net/wiki", "spaceKey": "DOCS" }
   sharepoint	driveId	folderId	{ "driveId": "b!Xyz…", "folderId": "01ABC…" }

3. Set the target: target vault (must be local) and target folder (default: imports), plus the converter.

4. Set the RBAC defaults: access roles, department and classification that newly imported articles receive. Existing articles keep their rights on updates.

5. Decide on AutoPromote: when enabled, imports are published directly without a manual review step; when disabled, they land in the configuration owner’s import review.

6. Choose the deletion behaviour (see below), set the cron schedule and enable the configuration.

Saving validates the configuration: missing required fields, invalid JSON, a non-local target vault, or a vault that is already the target of another configuration are rejected with a clear error message.

Operating: starting runs and reading reports

• Sync now starts a run immediately; the dry run shows what would happen (including lists of affected articles) without writing anything — recommended before the first real run and before enabling AutoPromote or deletion.
• The report per run counts: New / Changed / Unchanged / Deleted / Tombstoned / Hard-deleted / Promoted / Failed. Failed items include the reason; a single failure does not abort the whole run.
• “Already running”: the schedule, the admin panel and the sync button in the knowledge base share one lock per configuration — no two runs execute in parallel; a second start only reports the run in progress.
• If a run fails as a whole, the reason is in the report; the run is isolated and the progress cursor stays untouched — the next run resumes cleanly.

Deletion behaviour

What happens when a document disappears at the source is controlled by the policy:

Policy	Effect
Leave (default)	The article stays unchanged; the deletion only shows up in the report.
Tombstone	The article is marked as archived: status: archived + sync_deleted in the frontmatter. It stays findable but counts as outdated.
Delete	The article is removed permanently.

Two safeguards:

• Deletion threshold guard: if more than 50 % of at least 4 articles would disappear in one run, the run aborts and nothing is deleted — protection against faulty source listings.
• Reappearance reactivates: if the source document reappears, a tombstoned article is reactivated automatically — the tombstone frontmatter is cleaned up; a manually set status is kept.

Status values & remedies

Status	Cause	Remedy
Ok	Last run succeeded.	—
Failed	Run finished with an error (reason in the report).	Check the reason in the report (source reachable? path correct?), then run again.
NeedsReauth	SharePoint sign-in expired or was revoked.	Web: the configuration owner reconnects their Microsoft account — on the card at the top of the Knowledge sync tab. A connection made by another admin does not help the run. Desktop: in the knowledge base the sync button shows “Sign in & sync” — clicking it opens the Microsoft sign-in in the system browser; afterwards scheduled syncs run silently again.
Invalid	The configuration became invalid (e.g. the target vault is no longer local).	Open the configuration, fix the target, save again.
Never	Never ran yet.	Check the schedule or use “Sync now”.

Desktop note

On the desktop, the schedule only ticks while the app is open — a banner on the knowledge-sync page points this out (it only appears there). For continuous, unattended sync, the web mode is recommended.

Where to go next

• Synced articles & the sync button — the end-user view: banner, taking over an article, using the button
• Create a vault and assign rights
• Import and approve a document