govoplan-core/docs/PUBLIC_SECTOR_INTEGRATION_STRATEGY.md

Public-Sector Integration Strategy

GovOPlaN should integrate with the existing public-sector software landscape before deciding to replace specialist workflows. This document is the core strategy index. The executable connector catalogue lives in govoplan-connectors/docs/PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md.

The canonical cumulative maturity model and external-object DTO are documented in EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md.

Strategy Labels

Use one or more of these labels for every external system family:

• integrate: GovOPlaN talks to the system through a stable API/protocol.
• link: GovOPlaN stores external references and opens the external system for source-of-truth work.
• import: GovOPlaN consumes data or files into governed module storage.
• synchronize: GovOPlaN keeps selected records aligned both ways or through a source-of-truth rule.
• replace selected workflow: GovOPlaN may own a narrow workflow where the external product is weak, but does not replace the whole product family.
• no first-class support: GovOPlaN only stores manual references unless a deployment project creates a specific connector.

Initial Classification

System family	Examples	Default strategy	Likely owner
File providers	SMB/CIFS, WebDAV, Nextcloud, Seafile, SFTP, S3	integrate, import, link	govoplan-files, connector inventory in govoplan-connectors
Project/task management	OpenProject, Jira, Redmine, Microsoft Planner	link, synchronize selected records, replace selected workflow only after proof	govoplan-connectors, later govoplan-tasks or workflow modules
Identity providers	LDAP, Active Directory, OIDC, SAML, OpenDesk IDM	integrate, synchronize	govoplan-idm, govoplan-access
Mail and groupware	IMAP/SMTP, Open-Xchange, Exchange/M365, CalDAV/CardDAV	integrate, link	govoplan-mail, govoplan-calendar, govoplan-connectors
DMS/e-file/archive	d.velop/d.3, enaio, ELO, Fabasoft, CMIS, VIS/eAkte	link, import, synchronize selected metadata	govoplan-dms, govoplan-files, govoplan-records
ERP/finance/procurement	SAP, MACH, Infoma, DATEV, procurement feeds	export, import, synchronize; do not replace by default	govoplan-erp, govoplan-procurement, govoplan-ledger, govoplan-payments
Public-sector transport	FIT-Connect, XTA/OSCI, Peppol access points	integrate, publish, receive	dedicated protocol modules plus govoplan-connectors inventory
Standards registries	XRepository, XOE/V catalogues	link, import metadata/cache	govoplan-connectors, govoplan-xoev
Publication/data exchange	RSS, open-data APIs, API feeds, CSV/Excel drops	consume, publish, transform	proposed govoplan-datasources, proposed govoplan-dataflow, govoplan-reporting
Collaboration suites	Matrix, Jitsi, BigBlueButton, Nextcloud Talk, Collabora/OnlyOffice	integrate, link; native behavior only for governed evidence	govoplan-connectors, govoplan-dms, govoplan-workflow
Specialist Fachverfahren	register-specific and domain-specific systems	link first; integrate/import when a real project supplies contracts	domain module or deployment-specific connector

Landscape Catalogue

This catalogue is intentionally implementation-oriented. Each entry records the first API/auth/data assumptions needed to turn an inventory entry into a connector or module issue.

Citizen And Service Portals

• Strategy: integrate/link first; replace selected intake workflow only when a GovOPlaN portal package owns the complete journey.
• Protocol/API surface: REST/JSON APIs, form submission webhooks, OIDC/SAML login, eID interfaces where available, file-upload callbacks, case-status callbacks.
• Auth model: OIDC/SAML service clients, signed webhook secrets, tenant-scoped API keys, later eID/trust-provider handoff.
• Data shape: applicant identity reference, application form payload, attachment references, consent declarations, status events, receipt IDs.
• Deployment assumptions: externally reachable HTTPS, reverse proxy, portal DMZ separation, strict CSRF/origin settings, large upload path.
• Risks: personal data exposure, duplicate identity mapping, partial submissions, upload malware, inconsistent portal status models.
• MVP test path: submit a test application with one file, create a form submission/case/task stub, return a receipt and status reference.
• Owner/priority: govoplan-portal, govoplan-forms-runtime, govoplan-files, Wave 1.

DMS, E-File, Records, And Archives

• Strategy: link/import/synchronize selected metadata; do not replace the DMS by default.
• Protocol/API surface: CMIS, WebDAV, vendor REST APIs, S3/object archive staging, file-plan export/import, archive handoff APIs.
• Auth model: service accounts, OAuth/OIDC where supported, mTLS for regulated archives, secret references for vendor tokens.
• Data shape: document ID, version, file-plan/classification code, retention metadata, owner/case reference, external URL, checksum, lock/legal-hold state.
• Deployment assumptions: usually internal network or VPN, strict storage quotas, existing retention policies, archive immutability requirements.
• Risks: record duplication, broken legal hold, permission mismatch, version drift, destructive retention/export mistakes.
• MVP test path: create a connector inventory entry, test read-only metadata lookup, link one GovOPlaN file/case evidence item to an external document.
• Owner/priority: govoplan-dms, govoplan-records, govoplan-files, govoplan-connectors, Wave 2/5.

ERP, Finance, Procurement, And Accounting

• Strategy: export/import/synchronize selected records; replacement only by narrow domain decision.
• Protocol/API surface: vendor REST/SOAP APIs, CSV/XML batch exchange, SFTP, XRechnung/Peppol, XBestellung/procurement feeds, payment reconciliation files.
• Auth model: service accounts, client certificates, mTLS, SFTP keys, token references, environment-specific account separation.
• Data shape: debtor/creditor reference, payment request, invoice, order, budget/cost-center code, booking status, receipt/evidence reference.
• Deployment assumptions: batch windows, finance-system approval workflows, test tenants often separated from production by vendor process.
• Risks: financial posting errors, double export, tax/legal data retention, inconsistent master data, irreversible accounting handoff.
• MVP test path: dry-run export of one payment/accounting handoff file with checksum, validation report, and no remote posting.
• Owner/priority: govoplan-payments, govoplan-ledger, govoplan-xrechnung, govoplan-erp, govoplan-procurement, Wave 1/6.

Identity, IAM, And Directory Services

• Strategy: integrate/synchronize; access remains GovOPlaN's local authorization boundary.
• Protocol/API surface: LDAP, Active Directory, SCIM, OIDC, SAML, OpenDesk IDM APIs, group membership sync, account deactivation feeds.
• Auth model: bind accounts, service clients, OIDC/SAML metadata, SCIM tokens, certificate-backed clients where required.
• Data shape: account, user, group, membership, role claim, tenant/org-unit mapping, status, external directory ID.
• Deployment assumptions: directory is usually internal; identity provider may be organization-wide and not GovOPlaN-owned.
• Risks: privilege escalation through group mapping, stale memberships, account collision, deprovisioning latency, tenant-boundary mistakes.
• MVP test path: read-only directory profile test, map one external group to a tenant group, show a dry-run membership diff.
• Owner/priority: govoplan-idm, govoplan-access, Wave 1.

Groupware, Mail, Calendar, And Collaboration

• Strategy: integrate/link; native behavior only where GovOPlaN needs governed evidence or process state.
• Protocol/API surface: IMAP/SMTP, CalDAV/CardDAV, Open-Xchange APIs, Microsoft Graph/EWS, Matrix APIs, Jitsi/BigBlueButton APIs, Collabora/OnlyOffice integration points.
• Auth model: service accounts, delegated OAuth/OIDC, app passwords, mailbox credentials, groupware-specific tokens, secret references.
• Data shape: mailbox folder/message references, event/free-busy data, meeting URL, chat room ID, participant list, document-editing session reference.
• Deployment assumptions: often internal/existing tenant infrastructure; mail and calendar may be separate from identity even in OpenDesk-style stacks.
• Risks: mail credential exposure, calendar privacy, double invitations, room booking conflicts, chat/document data escaping retention rules.
• MVP test path: profile test for mailbox/calendar reachability, read-only folder/free-busy lookup, create a non-production event/message draft.
• 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 source of settlement truth.
• Protocol/API surface: payment provider APIs, redirect/callback flows, reconciliation files, SEPA/export formats, cash-register/cashier interfaces.
• Auth model: provider API keys, signed webhooks, client certificates, mTLS, tenant-specific merchant accounts.
• Data shape: payment intent, amount/currency, payer reference, provider transaction ID, settlement status, receipt, refund/cancellation reference.
• Deployment assumptions: public callback URLs, strict environment separation, PCI-sensitive providers, finance reconciliation cadence.
• Risks: duplicate charges, callback replay, amount mismatch, refund workflow gaps, evidence-retention mistakes.
• MVP test path: sandbox payment intent, signed callback verification, receipt evidence link, reconciliation dry-run.
• Owner/priority: govoplan-payments, govoplan-ledger, Wave 1/6.

Reporting, BI, Open Data, And Publication

• Strategy: consume/publish/transform; native reporting owns GovOPlaN views, not every external BI product.
• Protocol/API surface: SQL read replicas, CSV/Excel export/import, REST APIs, RSS/Atom, open-data APIs, SFTP/WebDAV publication targets.
• Auth model: read-only DB users, API tokens, SFTP keys, OAuth clients, public anonymous publication profiles where appropriate.
• Data shape: dataset metadata, schema/version, report parameters, generated file references, publication URL, freshness/lineage, validation results.
• Deployment assumptions: publication can be public or internal; generated datasets need retention and provenance.
• Risks: leaking restricted data, stale publications, schema drift, expensive queries, untraceable manual transformations.
• MVP test path: publish one report/export as a governed file plus RSS/Atom entry with checksum, timestamp, and permission check.
• Owner/priority: govoplan-reporting, govoplan-connectors, govoplan-datasources, and govoplan-dataflow, Wave 2. Reporting owns presentation/publication, Connectors owns transport, Datasources owns the governed source/materialization catalogue, and Dataflow owns transformations.

Public-Sector Protocols And Registries

• Strategy: integrate/publish/receive; protocol modules own protocol semantics.
• Protocol/API surface: FIT-Connect, XTA/OSCI, XRepository, XOE/V, XRechnung, XBestellung, Peppol, registry-specific Fachverfahren APIs.
• Auth model: certificates, mTLS, service accounts, destination credentials, protocol-specific trust anchors and key rotation.
• Data shape: transport envelope, payload schema/version, destination IDs, receipt/acknowledgement, message status, standard-specific metadata.
• Deployment assumptions: regulated trust chains, test/prod endpoint separation, formal onboarding, strict logging and retention expectations.
• Risks: invalid schemas, failed delivery receipts, certificate expiry, wrong destination routing, protocol version drift.
• MVP test path: validate a sample payload against a schema, test endpoint reachability in sandbox, store receipt/evidence reference.
• Owner/priority: govoplan-fit-connect, govoplan-xoev, govoplan-xrechnung, govoplan-xta-osci, govoplan-connectors, Wave 1/2.

File Providers And Shared Storage

• Strategy: integrate/import/link; files module owns GovOPlaN file semantics.
• Protocol/API surface: SMB/CIFS, WebDAV, Nextcloud, Seafile, SFTP, S3, local/object storage profiles.
• Auth model: service accounts, user credentials, app tokens, OAuth where supported, secret references, environment variables for deployment-managed credentials.
• Data shape: file ID/path, provider object ID, checksum, MIME type, size, version/ETag, owner, permission snapshot, imported file reference.
• Deployment assumptions: internal networks, large files, existing shares, variable permissions, provider-specific rate limits.
• Risks: permission mismatch, stale imports, overwrites, duplicate files, path traversal, storage growth.
• MVP test path: profile test, list folder, import one file into governed storage, keep provider reference and checksum.
• Owner/priority: govoplan-files, govoplan-connectors, Wave 0/1.

Project, Task, And Case-Adjacent Systems

• Strategy: connector-first for OpenProject/Jira/Redmine; native module only when GovOPlaN owns project semantics.
• Protocol/API surface: OpenProject API v3, webhooks, Jira/Redmine REST APIs, Microsoft Graph for Planner/Project where applicable.
• Auth model: API tokens, OAuth/OIDC apps, webhook secrets, service accounts.
• Data shape: project ID, work package/task ID, status, assignee reference, external URL, version/lock token, publish/sync trace.
• Deployment assumptions: external project tool remains source of truth for broad project management; GovOPlaN links selected records.
• Risks: task duplication, bidirectional sync conflicts, permission mismatch, over-mirroring comments/attachments.
• MVP test path: OpenProject profile test, project/work-package lookup, external-reference round-trip.
• Owner/priority: govoplan-connectors, later govoplan-tasks/workflow/cases consumers, Wave 0/2.

Specialist Fachverfahren

• Strategy: link first; integrate/import only when a deployment project supplies concrete contracts and a domain owner.
• Protocol/API surface: vendor APIs, CSV/XML batch imports, SFTP, database views, message queues, protocol-specific transports.
• Auth model: usually service accounts, VPN, mTLS, SFTP keys, or vendor tokens.
• Data shape: domain-specific record IDs, status, applicant/person references, file/evidence references, case/status events.
• Deployment assumptions: strongly local/vendor-specific, often no stable test API, data model differs by jurisdiction.
• Risks: brittle vendor contracts, legal source-of-truth ambiguity, high customization cost, migration expectations.
• MVP test path: inventory entry and manual external-reference link; require a project-specific connector issue before automation.
• Owner/priority: domain module or deployment-specific connector, case by case.

Prioritization Rules

1. Start with connectors that unblock Wave 0 or Wave 1 reference journeys.
2. Prefer open standards and self-hosted/open-source APIs where they are common in public-sector deployments.
3. Treat inventory-only entries as useful because operators need a map of their software landscape even before automation exists.
4. Keep connector code in the owning connector/protocol module. Domain modules consume capabilities, DTOs, external references, and events through core.
5. Every executable connector needs health diagnostics, secret-reference handling, lifecycle state, audit events, and retirement behavior.

Connector Catalogue Handoff

govoplan-connectors owns the detailed catalogue entry shape:

• connector type key
• category and owner module
• supported directions and trigger modes
• credential and secret handling
• health check and diagnostics payload
• external-reference shape
• required capabilities and optional module combinations
• lifecycle support

Core should only keep strategy, routing, and cross-module architecture notes. Connector implementation and public-sector target inventory belong in govoplan-connectors.