govoplan-connectors/docs/MEDIAWIKI_BLUESPICE_CONNECTOR.md

MediaWiki and BlueSpice Knowledge Connector

The knowledge connector integrates an external MediaWiki or BlueSpice instance without making Connectors the owner of native knowledge semantics. Connectors owns endpoint and credential governance, Action API transport, discovery, synchronization, identity-stable snapshots, diagnostics, and publication recovery. Wiki continues to own GovOPlaN-native spaces, pages, drafts, revisions, comments, and publishing policy.

Configure and discover

Create an active governed connector definition and configuration with:

• provider mediawiki or bluespice;
• protocol mediawiki, action_api, or mediawiki_action_api;
• an absolute HTTP(S) endpoint without embedded credentials; and
• an optional Core credential-envelope reference. Publication requires the credential; public read-only sources may omit it.

Core validates the endpoint and every redirect against the deployment egress, DNS/IP-pinning, peer, downgrade, and response-size policies. Credentials can be bearer/access tokens or username/password values resolved only for the current tenant, actor, module, target scope, and server. They never enter connector profiles, snapshots, diagnostics, URLs, or API responses.

A knowledge profile selects desired maturity and authority and maps each included source namespace to a target Wiki space reference and path prefix. Every profile also supplies a tenant or restricted fallback visibility. A restricted fallback needs at least one normalized Search ACL token such as group:<id>, role:<id>, membership:<id>, account:<id>, identity:<id>, function:<id>, or scope:<permission>.

Discovery queries site and current-user metadata. It records the product, version, API/PHP version, extensions, namespaces, advertised edit right, capabilities, a stable discovery digest, and sanitized diagnostics. BlueSpice permission and discussion extensions are detected where advertised. Standard MediaWiki does not expose complete page ACL semantics through the base Action API, so discovery reports that the configured namespace fallback will be used.

Synchronize and preserve identity

Run one bounded full backfill and then bounded recent-change deltas. Every run requires an idempotency key; exact replay returns the original evidence without contacting the source, while reusing the key with different inputs is rejected. The profile stores only its latest cursor and high-watermark. Runs retain counts, redacted effects, diagnostics, configuration/discovery provenance, and transport evidence.

Snapshots use the MediaWiki page id as stable identity and preserve revision id, canonical URL, content digest, namespace, title, source timestamp, and observed timestamp. Page content mapping covers categories, links, file references, discussion references, revision author references, redirect targets, permission metadata, target space/path, and detected wikitext macros. Referenced files remain external references; binary transfer and attachment ownership remain with Files or DMS.

Moves update the existing stable page. Deletions use the stable page id when the provider supplies it and otherwise match a previously synchronized namespace and title. An unmatched deletion becomes a separate tombstone with an explicit diagnostic instead of silently deleting an unrelated page. Permission changes are part of the content digest and therefore update the current snapshot even when page text is unchanged.

Desired maturity is an operator ceiling. A read-only profile cannot be used for synchronization, migration preview, or publication merely because the provider advertises those capabilities.

Search and access safety

When Search is installed, Connectors registers connectors.mediawiki.pages for the external_knowledge_page resource type. Backfill includes only active, non-deleted pages from active profiles. Restricted documents carry the current snapshot ACL; tenant documents carry no narrower ACL.

Search performs a fail-closed authorization recheck for every result. It requires the external-knowledge read permission, an exact tenant match, an active profile, a current non-deleted page, and—when restricted—intersection with the current account, membership, identity, group, role, function, or scope tokens. Consequently, an ACL change takes effect even before a deferred index update completes. Immediate index updates remove deleted pages and refresh ACLs; the next Search rebuild reconciles any transient writer failure. Search also removes source projections when Connectors is disabled.

Publish and reconcile

Publication requires the publish permission, an active profile and configuration, discovered provider publication capability, desired maturity at least publish, an idempotency key, page title/body, and an optional expected external revision. The Action API edit carries baserevid when supplied and uses a credential-provided or freshly acquired CSRF token.

Before remote I/O, Connectors prepares a durable forward-recovery operation with request digest, expected revision, cursor, profile/configuration revision, and resource identity. A confirmed provider response stores the stable page and new revision and completes the recovery evidence. A definitive provider rejection is terminal. A timeout, invalid response, or server failure after dispatch becomes outcome-unknown: do not retry with another key until an operator compares the provider page/revision and reconciles the recovery operation. Local rollback cannot undo a confirmed external edit.

Migration preview into Wiki

Migration is intentionally a dry-run in this slice. The request names a target space, supported macro set, existing target paths/source identities, and existing attachment names. The preview is bounded to 500 source pages and records a source fingerprint and high-watermark. It reports create, update, or conflict effects plus:

• target path already owned by a different external page;
• attachment filename collisions;
• unsupported macros;
• pages outside the requested target space; and
• truncation at the configured limit.

can_apply=true means the bounded preview contains no error or conflict and is not truncated. It does not write Wiki pages. A future target-side migration worker must use the optional connector capability and Wiki-owned mutation contract, revalidate the preview fingerprint, and keep native Wiki permissions and revision history authoritative.

Operations and privacy

Provider state exposes profile product/maturity, active-object count, latest run status, health, recovery attention, and last success time without endpoint, credential, title, ACL, or content data. Existing snapshots may remain available during an outage only to principals still authorized by current local profile and ACL state; their health and freshness remain explicit.

Data-subject exports include only minimized operator attribution for profile updates and synchronization/migration/publication runs. They exclude endpoints, credentials, page content, titles, ACLs, namespace mappings, idempotency keys, request hashes, effects, diagnostics, provenance, and transport evidence. Attribution and external-operation evidence is retained for governance rather than automatically erased.