135 lines
7.1 KiB
Markdown
135 lines
7.1 KiB
Markdown
# 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.
|