From 51bf14f3762aeacec05f4f7565341e1a419e445e Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Wed, 19 Aug 2026 23:15:35 +0200 Subject: [PATCH] docs(core): define collaboration connector strategy --- docs/PUBLIC_SECTOR_INTEGRATION_STRATEGY.md | 67 ++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/docs/PUBLIC_SECTOR_INTEGRATION_STRATEGY.md b/docs/PUBLIC_SECTOR_INTEGRATION_STRATEGY.md index 7a0adad..d065235 100644 --- a/docs/PUBLIC_SECTOR_INTEGRATION_STRATEGY.md +++ b/docs/PUBLIC_SECTOR_INTEGRATION_STRATEGY.md @@ -141,6 +141,73 @@ connector or module issue. - Owner/priority: `govoplan-mail`, `govoplan-calendar`, `govoplan-connectors`, Wave 1/2. +#### Collaboration-suite boundary and hand-offs + +Collaboration remains connector-first. The product named below never changes +which GovOPlaN module owns the administrative meaning of the work: + +| External family | Initial posture | GovOPlaN semantic owner | Connector-owned boundary | +| --- | --- | --- | --- | +| Collabora Online, OnlyOffice, Nextcloud Office | Link an externally edited document and its editing session; import a governed rendition only when required | DMS owns document/version, lock, review, approval, retention, and collaboration-session evidence; Files owns stored bytes | Discovery, endpoint health, WOPI/vendor session exchange, callbacks, and provider object references | +| Matrix, Mattermost, Rocket.Chat, Nextcloud Talk | Create or link a room/thread for a governed work context; do not mirror all conversation history by default | The initiating Case, Workflow, or Task owns the work-context link and disposition; DMS/Records own retained evidence deliberately captured from it | Room/thread creation, membership synchronization, webhook/event normalization, and stable external links | +| Jitsi and BigBlueButton | Provision or link a conference for an existing appointment/event | Appointments owns booking intent; Calendar owns event, attendee, invitation, and time semantics | Conference provisioning, join/moderator references, provider lifecycle, and bounded attendance/result callbacks | +| OpenProject and comparable project suites | Link first, then publish or synchronize selected work packages | Tasks owns GovOPlaN task state; Workflow owns orchestration; Cases own case state and evidence references | Project/work-package lookup, publish/synchronize transport, webhooks, version tokens, and external URLs | +| Cross-suite activity streams | Consume normalized, bounded events only for an authorized work context | The receiving module decides whether an event changes state or becomes evidence; Audit records the GovOPlaN operation | Provider subscriptions, cursor/checkpoint handling, signature validation, event normalization, and replay protection | + +Native collaboration behavior is justified only when GovOPlaN must own the +semantic state, authorization decision, audit evidence, retention/legal-hold +rule, or configuration-package fragment. Endpoint profiles, tokens, health, +protocol clients, provider IDs, retries, and webhook transport remain in +Connectors (or the owning protocol connector). A feature module consumes a +Core capability/DTO and must still start and fail explicitly when that optional +connector is absent; it never imports a provider client. + +The minimum hand-off sequences are: + +1. **Appointment to conference:** Appointments confirms the booking intent; + Calendar creates or updates the event and invitations; an optional + conference connector provisions the room idempotently and returns an + opaque join reference. Calendar stores that reference with the event, not + the provider credential. +2. **Case or Workflow to collaborative document:** the initiating module asks + DMS for a governed document/session; DMS requests an optional office-suite + connector session and retains version, lock, approval, and callback + evidence. The Case/Workflow keeps only the DMS reference. +3. **Case, Workflow, or Task to chat:** the semantic owner requests a room or + thread with an idempotency key and bounded membership intent. The connector + returns an external reference; capturing messages as evidence requires an + explicit DMS/Records action and policy decision. +4. **Task or Workflow to project suite:** Tasks supplies the task payload and + Workflow supplies correlation; the OpenProject connector publishes or + reconciles the work package and returns versioned external-reference and + retry/conflict evidence. Neither consumer writes connector tables. + +Every executable collaboration connector must pass the common connector +contract checks plus a provider-focused minimum proof: + +- optional-module startup and partial compositions work without the provider; +- profile health uses secret references and redacts credentials and remote + response bodies; +- tenant/resource authorization is checked before discovery, provisioning, + lookup, synchronization, or evidence capture; +- dry-run/simulation performs no remote mutation and explains unsupported + operations; +- create/publish calls are idempotent, retries preserve the same external + reference, and outcome-unknown or version conflicts remain reconcilable; +- callbacks/webhooks verify authenticity, tenant/profile binding, replay + protection, and bounded payloads; +- disable/retire behavior revokes new use while preserving non-secret audit and + external-reference evidence; +- Collabora/OnlyOffice prove discovery plus one non-production editing-session + round trip; Matrix/Mattermost/Rocket.Chat prove room lookup/create plus one + authenticated bounded event; Jitsi/BigBlueButton prove conference + provision/cancel; OpenProject proves project/work-package lookup, idempotent + publish, and conflict handling. + +These are connector acceptance tests, not a claim that those connectors are +already implemented. Their implementation state remains in the owning +connector issues and catalogue. + ### Payment And Public Cashier Systems - Strategy: integrate/export/import; keep the payment provider or cashier as