Implement: Integration: XWiki (External Knowledge)

[rubenvdlinde]

OpenSpec Change: integration-xwiki

Spec path: openspec/changes/integration-xwiki

Depends on: #1307 (pluggable-integration-registry)

⚠️ Blocked — Waiting on Dependencies

• Implement: Pluggable Integration Registry #1307 — umbrella not yet merged to development

When the umbrella is merged, remove the blocked label and add ready-to-build to let Hydra pick this up.

Spec PR: #1300

Real-world consumer

ConductionNL/deskdesk ships a desk-booking app whose Part 4 tutorial demonstrates the xWiki integration end to end. The app currently uses a wrong-shape implementation (custom knowledge_article schema + sync) as a placeholder. When this leaf lands, deskdesk:

1. Drops the knowledge_article schema, the KnowledgeTab.vue custom sidebar component, and the DetailPageWrapper.vue workaround
2. Adds "linkedTypes": ["xwiki"] to the desk schema configuration
3. The XwikiProvider supplies the sidebar tab + widget + reference rendering automatically
4. Part 4 of the academy tutorial gets a clean rewrite teaching the correct pattern

The xWiki dev environment lives in openregister/docker-compose.yml under the xwiki / integrations profile (docker compose --profile xwiki up -d xwiki). Container hostname openregister-xwiki:8080 is reachable from the Nextcloud container; host port 8086 for browser access.

Tasks

1. Backend

• 1.1 Create lib/Service/Integration/Providers/XwikiProvider.php
  • id='xwiki', label='Articles', icon='FileDocumentMultiple', group='external'
  • requiredApp=null, storage='external'
  • getOpenConnectorSource() returns 'xwiki'
• 1.2 Declare auth requirements (basic or oauth2, configurable at source level)
  • authRequirements() returns the OpenConnector source's declared auth type
• 1.3 Delegate CRUD to ExternalIntegrationRouter
  • Provider stays thin; routing logic lives in the umbrella's router
• 1.4 Ship OpenConnector source config template config/openconnector-sources/xwiki.yaml
  • YAML template: base URL, auth type, headers (Accept: application/json), pagination
• 1.5 DI-tag the provider in lib/AppInfo/Application.php
  • IntegrationRegistry discovers it automatically
• 1.6 Unit tests (OpenConnector client mocked)
  • At least 5 test methods: registration, auth, list pages, get page, missing-page exception

2. Frontend — Tab

• 2.1 CnXwikiTab.vue — linked pages with title + full breadcrumb
  • Row format: title + breadcrumb (Wiki / Department / Subspace / Page)
  • Link-by-URL (parses to space.page)
  • Link-by-path
  • Unlink action
  • Auth-expired banner
• 2.2 Barrel + tests
  • src/components/CnXwikiTab/index.js
  • Tests covering URL parsing, breadcrumb rendering, auth banner

3. Frontend — Widget

• 3.1 CnXwikiCard.vue — 4 surfaces with detail-page text preview
  • user-dashboard: recent linked pages
  • app-dashboard: scoped to app
  • detail-page: linked pages + 500-char text preview (macros stripped) + link to full page
  • single-entity: page-title + breadcrumb chip
• 3.2 Barrel + surface tests
  • All four surfaces tested
  • Security: macros stripped, no <script> in preview output

4. Registration

• 4.1 src/integrations/builtin/xwiki.js — register with referenceType: 'xwiki'
  • Tab + widget components wired
  • Schema reference properties can render an xwiki chip via referenceType

5. Quality

• 5.1 Parity gate, nl+en translations, strict checks, ESLint
  • scripts/check-integration-parity.sh passes
  • nl + en translations for every user-facing string
  • composer check:strict passes
  • npm run lint passes

6. Acceptance verification

• 6.1 E2E: configure OpenConnector xwiki source, link a page, verify breadcrumb in tab + text preview on detail-page
  • Runs against the dev environment's openregister-xwiki container
• 6.2 Link-by-URL test: paste full URL, verify resolution to canonical space.page
  • https://wiki.example/xwiki/bin/view/Dept/Policy/Privacy → space='Dept.Policy', page='Privacy'
• 6.3 Auth test, hide test, reference-property test
  • Auth-expired banner when source credentials fail
  • Provider hidden from registry when OpenConnector source missing/disabled
  • Reference-property renders xwiki chip in CnFormDialog
• 6.4 Security: verify XWiki macros are NOT executed in preview (text-only)
  • Render a page with {{velocity}} macro
  • Confirm macro stripped from preview, no <script> in output
  • ADR-005 compliance

[rubenvdlinde]

integration-xwiki leaf — implemented, two stacked PRs open

The worked external-storage example for the pluggable-integration-registry umbrella.

Half	PR	Stacked on
Backend (XwikiProvider + DI registration + OpenConnector source template + user guide + unit tests)	openregister #1493	#1490 → #1475 → … → development
Frontend (CnXwikiTab + CnXwikiCard + xwikiIntegration + registration + tests)	nextcloud-vue #213	#210 → #209 → #204 → #202 → beta

What's in it

• PHP — XwikiProvider (storage external, group external, OpenConnector source xwiki, requiredApp: openconnector). All CRUD delegated to ExternalIntegrationRouter; health() defers to probe(). normalizeRow() shapes rows to { id, reference, title, space, page, breadcrumb, url, content }. AD-1 (text-only preview), AD-2 (link by URL or Space.Page path), AD-3 (breadcrumb rows). OpenConnector source template at docs/Integrations/xwiki-openconnector-source.yaml (config/ is gitignored) + a docs/Integrations/xwiki.md user guide.
• JS — CnXwikiTab (linked pages + breadcrumb, link-by-URL/path form, unlink, reconnect/unavailable banner on 503, linked/unlinked events). CnXwikiCard (surface-aware: detail-page text preview with macros not executed + "Open in XWiki" link; compact list on dashboards; title+breadcrumb chip on single-entity for referenceType: 'xwiki'). xwikiIntegration descriptor + registerXwikiIntegration() — a leaf, not added to builtinIntegrations; OpenRegister's bundle registers it explicitly.

Tests

• PHP: XwikiProviderTest — 10 tests / 38 assertions; composer phpcs|phpmd|psalm clean; phpunit-unit.xml green
• JS: CnXwikiTab.spec.js (7), CnXwikiCard.spec.js (8), tests/integrations/xwiki.spec.js (6) — 21 total, all green. Full nextcloud-vue suite: 74 suites, 1032 passing, 4 pre-existing failures unrelated.
• Acceptance: link-by-URL, reference-property, and "macros not executed in preview" are covered by the component tests. Live E2E (against a running XWiki via an OpenConnector source) is deferred until the umbrella + leaf PRs merge and deploy.

Spec deviations (recorded in tasks.md)

• requiredApp: 'openconnector' (not null) — accurate for the admin UI
• source-config template at docs/Integrations/xwiki-openconnector-source.yaml (config/ gitignored)
• provider registered via addProvider() at boot, not a DI tag — matches the umbrella mechanism

Note

docs/components/_generated/CnXwikiTab.md / CnXwikiCard.md partials still need regenerating (cd docusaurus && npm run prebuild:docs) — docusaurus deps weren't installed in the dev env; same situation as CnFilesCard/CnTagsCard/CnAuditTrailCard from nextcloud-vue #204.

[rubenvdlinde]

Live verification — XWiki side ✅, Nextcloud side blocked on deploy

Spun up xwiki:lts-postgres-tomcat 17.10 locally (openregister-xwiki, host port 8086, ROOT context — REST at /rest/, superadmin enabled). Created a test page via REST and inspected the page representation:

PUT /rest/wikis/xwiki/spaces/Sandbox/pages/IntegrationTest   → 201, page created
GET /rest/wikis/xwiki/spaces/Sandbox/pages/IntegrationTest   → {
  id: "xwiki:Sandbox.IntegrationTest", space: "Sandbox", name: "IntegrationTest",
  title: "Integration Test Page", xwikiAbsoluteUrl: "http://localhost:8086/bin/view/Sandbox/IntegrationTest",
  content: "...{{velocity}}$xwiki.getDocument{{/velocity}}..."  ← RAW xwiki/2.1 syntax, NOT rendered HTML
  hierarchy: { items: [ {label:"xwiki",type:"wiki"}, {label:"Sandbox",type:"space"}, {label:"IntegrationTest",type:"document"} ] },
  version, modified, …
}
GET /bin/get/Sandbox/IntegrationTest?xpage=plain   → "<p>...the $xwiki.getDocument macro...</p>"  ← rendered HTML (macros run server-side, in XWiki's sandbox)

Folded into the OpenConnector source template (docs/Integrations/xwiki-openconnector-source.yaml, commit b673f7e5c):

• breadcrumb should map from XWiki's native hierarchy.items[].label (AD-3) — confirmed it exists and has the right shape.
• For the AD-1 text preview, the source should fetch the rendered body from /bin/get/{Space}/{Page}?xpage=plain (XWiki executes macros server-side; they're never executed inside Nextcloud — the widget only reads text content). Mapping content straight from the REST content field is still safe (macro markup is inert text), just shows raw wiki source. Documented both ways.
• Confirmed the rest of the mapping: id → reference ("xwiki:Space.Page"), title, space, name → page, xwikiAbsoluteUrl → url.
• No PHP change needed — XwikiProvider::normalizeRow() already has the breadcrumb (space+title) and content (renderedContent) fallbacks, so it works against either mapping.

Nextcloud-side runtime verification is blocked until the cross-repo PRs merge + deploy:

• The container's openregister has the umbrella classes (lib/Service/Integration/*) but not the Application.php wiring (registerIntegrationRegistry() / bootBuiltinIntegrationProviders() aren't present) — so the registry isn't populated at runtime there. That wiring lands with the umbrella PR stack (feat(integration-registry): contract + registry + external router (umbrella PR 1/N) #1467→feat(integration-registry): admin UI surfacing auth status (umbrella PR 5/N) #1475).
• The @conduction/nextcloud-vue frontend bundle in the deployed app isn't built with the registry / CnXwikiTab / CnXwikiCard code — those land with the nc-vue PR stack (fix 1-1-1970 date on published #202→[Changelog CI] Add Changelog for Version 0.1.50 #213).
• Once both stacks merge to development/beta and the bundle is rebuilt + deployed: configure the xwiki source in OpenConnector (import the template, point location at http://openregister-xwiki:8080/rest/wikis/xwiki, auth superadmin:system for the local instance), then run the live E2E — Articles tab populates with the test page + its breadcrumb, detail-page text preview renders (macros not executed), admin Integrations page shows the xwiki row's health.

XWiki is left running with the Sandbox.IntegrationTest sample page in place for that follow-up.