198 lines
7.5 KiB
Markdown
198 lines
7.5 KiB
Markdown
# govoplan-connectors Concept
|
|
|
|
## Purpose
|
|
|
|
`govoplan-connectors` is the integration catalogue and connector coordination
|
|
module. It helps GovOPlaN connect to existing public-sector and organizational
|
|
systems without pretending to replace every specialist platform.
|
|
|
|
The module owns connector metadata, connection profiles, health checks, test
|
|
results, credential references, and generic integration events. Protocol-heavy
|
|
or domain-heavy integrations may live in dedicated modules once their scope is
|
|
clear.
|
|
|
|
Connector capability is not source ownership. Each configured binding also
|
|
declares whether GovOPlaN is authoritative, the external system is
|
|
authoritative, GovOPlaN keeps a mirror, both sides use governed synchronization,
|
|
GovOPlaN supplies only a governance overlay, or the object is link-only. The
|
|
same connector may be configured differently by tenant, service, object type,
|
|
or field group.
|
|
|
|
Detailed follow-up documents:
|
|
|
|
- [Public-sector integration catalogue](PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md)
|
|
- [Connector source lifecycle](CONNECTOR_SOURCE_LIFECYCLE.md)
|
|
- [OpenProject connector concept](OPENPROJECT_CONNECTOR.md)
|
|
- [OpenDesk integration map](OPENDESK_INTEGRATION_MAP.md)
|
|
|
|
## Shared runtime boundary
|
|
|
|
Connector transports use the versioned Core runtime contract for bounded dry
|
|
runs and diagnostics. Connectors owns endpoint discovery, authentication
|
|
hand-off, protocol reads, retry/backoff, and source health. A consuming module
|
|
owns domain mappings and mutations: Addresses, for example, owns contact and
|
|
vCard semantics even when Connectors supplies reusable LDAP, CardDAV, Exchange,
|
|
or Google transport patterns.
|
|
|
|
Dry runs carry an immutable input hash, source revision and fingerprint,
|
|
redacted effects, diagnostics, truncation state, and an apply token. Apply must
|
|
reject a changed input or source revision. URLs and diagnostics never contain
|
|
credential material; they retain only credential-envelope references.
|
|
|
|
## Ownership
|
|
|
|
The module owns:
|
|
|
|
- connector catalogue entries and capability metadata
|
|
- connection profiles and endpoint configuration
|
|
- credential references and test diagnostics
|
|
- generic webhook/polling/job coordination metadata
|
|
- connector health status and last-test evidence
|
|
- operator-visible integration inventory
|
|
- cross-module discovery of available external capabilities
|
|
- supported integration maturity, source-authority modes, operation limits,
|
|
and effect/reconciliation behavior for each connector type
|
|
|
|
The module does not own:
|
|
|
|
- governed datasource identity, staging, materializations, frozen states, or
|
|
consumer read semantics, owned by `govoplan-datasources`
|
|
- file storage semantics, owned by files/DMS
|
|
- identity provisioning semantics, owned by IDM/access
|
|
- mail/calendar semantics, owned by mail/calendar
|
|
- case/workflow/task/domain records
|
|
- payment, ledger, XRechnung, XTA/OSCI, FIT-Connect, or XOE/V protocol
|
|
semantics once those are dedicated modules
|
|
|
|
## Connector Categories
|
|
|
|
Initial catalogue categories:
|
|
|
|
- project management and task systems such as OpenProject
|
|
- DMS/e-file/archive systems
|
|
- file providers such as Nextcloud, Seafile, WebDAV, SMB/NFS, object storage
|
|
- identity providers such as LDAP, Active Directory, OIDC, SAML, OpenDesk IDM
|
|
- groupware such as Open-Xchange mail/calendar
|
|
- ERP, finance, accounting, payment, and cash-register systems
|
|
- public-sector protocols such as FIT-Connect, XTA/OSCI, XRechnung, XOE/V
|
|
- reporting, BI, RSS/API publication, and open-data endpoints
|
|
|
|
## Core Contracts
|
|
|
|
The module should integrate through:
|
|
|
|
- module manifest metadata, route factories, permissions, and migrations
|
|
- a connector catalogue API for listing available connector types
|
|
- a connection profile API with secret references, not plaintext secrets
|
|
- a provider declaration that composes authority mode, maturity, supported
|
|
operations, revisions/freshness, health, limits, idempotency, conflicts,
|
|
evidence, and reconciliation behavior
|
|
- capability declarations such as `connectors.catalog`,
|
|
`connectors.profileTester`, and `connectors.health`
|
|
- events such as `connector.profile_created`, `connector.test_succeeded`,
|
|
`connector.test_failed`, and `connector.health_changed`
|
|
- configuration-package fragments for required external systems
|
|
|
|
Domain modules should ask whether a connector capability exists and request a
|
|
profile/test result through core-mediated capabilities. They must not import
|
|
connector implementation modules directly.
|
|
|
|
Data-oriented consumers use a two-layer path: Connectors publishes a
|
|
provider-specific datasource origin, then Datasources registers and governs it.
|
|
Dataflow, Workflow, Reporting, and other consumers use Datasources rather than
|
|
calling the connector origin directly.
|
|
|
|
## Reference Journeys
|
|
|
|
### OpenProject Connector First
|
|
|
|
1. Operator registers an OpenProject connection profile.
|
|
2. Connector tests API reachability and authentication.
|
|
3. A future project-management decision can use the connector before a native
|
|
`govoplan-projects` module exists.
|
|
4. Cases/tasks/workflow may link to external project/task references through
|
|
stable external-reference DTOs.
|
|
|
|
### Public-Sector Integration Catalogue
|
|
|
|
1. Operator records which external systems exist in an organization.
|
|
2. GovOPlaN identifies common protocols and missing connectors.
|
|
3. Configuration packages can declare required connector profiles.
|
|
4. Health/status pages show whether required integrations are ready.
|
|
|
|
### OpenDesk Profile
|
|
|
|
1. Operator records OpenDesk component profiles for identity, mail, calendar,
|
|
files/documents, and OpenProject where present.
|
|
2. Connectors shows which components are configured, tested, degraded, or
|
|
missing.
|
|
3. Domain modules enable optional behavior by checking capabilities through
|
|
core, not by importing connector or OpenDesk-specific implementation code.
|
|
|
|
## MVP Slice
|
|
|
|
The first implementation should provide:
|
|
|
|
- connector type registry
|
|
- connection profile CRUD with secret references
|
|
- connection test result records
|
|
- WebUI catalogue and profile pages
|
|
- configuration-package fragment support
|
|
- generic external-reference DTOs
|
|
- source-authority binding and provider-operation metadata
|
|
- health summary provider
|
|
|
|
## Permissions
|
|
|
|
Candidate scopes:
|
|
|
|
- `connectors:catalog:read`
|
|
- `connectors:profile:read`
|
|
- `connectors:profile:write`
|
|
- `connectors:profile:test`
|
|
- `connectors:secret:manage`
|
|
- `connectors:admin`
|
|
|
|
## Data Model Sketch
|
|
|
|
Candidate tables:
|
|
|
|
- `connector_types`
|
|
- `connector_profiles`
|
|
- `connector_profile_tests`
|
|
- `connector_health_status`
|
|
- `external_references`
|
|
|
|
Plaintext credentials must never be stored in connector tables. Use secret
|
|
references and the platform secret contract.
|
|
|
|
## WebUI
|
|
|
|
Initial route contributions:
|
|
|
|
- `/connectors`
|
|
- `/connectors/profiles/:profileId`
|
|
|
|
The UI should show profile status, last test result, capability labels, required
|
|
configuration-package dependencies, and external-reference search where a
|
|
connector supports it.
|
|
|
|
## Tests
|
|
|
|
Minimum tests:
|
|
|
|
- core starts with connectors installed and no domain modules present
|
|
- profile validation rejects plaintext secret echoing
|
|
- connection tests record success/failure diagnostics without leaking secrets
|
|
- configuration package can require a connector profile
|
|
- domain-module optional behavior can detect connector capabilities without
|
|
imports
|
|
|
|
## Open Decisions
|
|
|
|
- Whether protocol-specific connector modules depend on `govoplan-connectors`
|
|
or only share kernel contracts.
|
|
- Which connector type should be first after OpenProject.
|
|
- How much polling/webhook scheduling belongs here versus workflow/ops.
|
|
- Whether external-reference indexing should move to search/dataflow later.
|