[OpenSpec] 2026-06-15-softwarecatalog-contacts-to-nc

[github-actions]

⚠️ OpenSpec-managed issue — this content is automatically synced
from the openspec/ directory. Manual edits will be overwritten on next sync.

Artifacts

• ✅ Metadata
• ✅ Proposal
• ✅ Specs
• ✅ Design
• ✅ Tasks
• 🔲 Plan
• 🔲 Review

Summary

Softwarecatalog's top-level navigation currently exposes Organisations
(Organisaties) and Contacts (Contactpersonen) as first-class
transactional sections backed by two app-local OpenRegister schemas —
organisatie and contactpersoon — in the voorzieningen register. These two
schemas store raw person/organisation identity (names, e-mail, phone,
website, logo, CBS/KvK-style code, job function), which per cross-app contract
#2 is the responsibility of the Nextcloud addressbook
(OCP\Contacts\IManager), not of an app-local party schema.

This change moves person/org identity into Nextcloud Contacts and reduces
softwarecatalog's footprint to only the catalog-specific relationship/role
that genuinely belongs to it: which contact is the maintainer/vendor/registrant
of which software product, in which catalog role, under which participation.
Each relationship record is keyed by contactsUid (a reference into the NC
addressbook) instead of embedding identity. The identity fields (voornaam,
achternaam, e-mailadres, naam, website, logo, telefoonnummer, …)
are owned by the NC Contact; softwarecatalog reads them through the contacts
abstraction, never duplicating them.

The top-level Organisations and Contacts menu entries are removed from
the primary navigation; their identity-listing function is served by the
Nextcloud Contacts app. The remaining catalog-specific relationship records
(organisation participation, contact roles on products) are surfaced in
context on the software product / organisation detail views and grouped
under the existing Settings area where they are administered, not as
top-level identity browsers. All existing routes stay routable for deep
links during the transition.

A fail-safe, idempotent repair step (lib/Repair/MigrateContactsToNc.php)
resolves or creates an NC Contact for every existing organisatie and
contactpersoon object — matching on e-mail (and on CBS/KvK code for
organisations) — writes the resulting contactsUid onto the kept relationship
record, and never deletes the source object until it has been migrated.

Specs

• 📄 softwarecatalog-contacts-to-nc

Tasks

• Confirm the Nextcloud addressbook (OCP\Contacts\IManager) is the
• Confirm pipelinq/lib/Service/ContactSyncService.php (and
• Confirm lib/Settings/softwarecatalogus_register.json organisatie +
• Confirm the catalog-specific relationship/role fields to KEEP (rollen,
• Confirm the external Softwarecatalogus/ VNG repo is OUT of scope.
• Add lib/Service/SoftwareCatalogContactSyncService.php modeled on
• Resolve identity reads (name/e-mail/logo/website) through the contacts
• In lib/Settings/softwarecatalogus_register.json (or an ADR-037 fragment
• Drop identity properties from contactpersoon (voornaam,
• Drop identity properties from organisatie (naam, beschrijvingKort,
• Remove menu[] entries Organisaties (order 20) and Contactpersonen
• Keep pages[] Organisaties, Contactpersonen, ContactpersoonDetail
• Update Contactpersonen index config.columns from identity columns
• Surface contact-role and organisation-participation administration from
• Add lib/Repair/MigrateContactsToNc.php, registered in
• For each organisatie/contactpersoon object
• Guard on contactsUid presence → re-run is a no-op (idempotent).
• Never delete/retire the source object's identity fields until
• Use POSITIONAL args for OCP calls (getAppValue, IManager) per the
• Repoint lib/BackgroundJob/OrganizationContactSyncJob.php to refresh
• cd softwarecatalog && openspec validate softwarecatalog-contacts-to-nc --strict passes (exit 0).

Design

See design.md for technical design details.

---

Synced from openspec/changes/archive/2026-06-15-softwarecatalog-contacts-to-nc by OpenSpec workflow
App: stackiq