diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5fd4061 --- /dev/null +++ b/.gitignore @@ -0,0 +1,23 @@ +__pycache__/ +*.py[cod] +*.egg-info/ +.pytest_cache/ +.mypy_cache/ +.ruff_cache/ +.venv/ +build/ +dist/ +node_modules/ +webui/node_modules/ +webui/dist/ +*.tsbuildinfo +.component-test-build/ +.module-test-build/ +.policy-test-build/ +.template-preview-test-build/ +.import-test-build/ +webui/.component-test-build/ +webui/.module-test-build/ +webui/.policy-test-build/ +webui/.template-preview-test-build/ +webui/.import-test-build/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..faa685e --- /dev/null +++ b/README.md @@ -0,0 +1,17 @@ +# govoplan-connectors + +`govoplan-connectors` will own integration catalogues and generic external +system connection patterns for GovOPlaN. + +The module should make external systems discoverable, testable, and usable +without taking ownership of their business semantics. Domain-specific modules +remain responsible for case, file, workflow, payment, mail, identity, document, +or reporting behavior. + +See: + +- [Connector concept](docs/CONCEPT.md) +- [Public-sector integration catalogue](docs/PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md) +- [Connector source lifecycle](docs/CONNECTOR_SOURCE_LIFECYCLE.md) +- [OpenProject connector concept](docs/OPENPROJECT_CONNECTOR.md) +- [OpenDesk integration map](docs/OPENDESK_INTEGRATION_MAP.md) diff --git a/docs/CONCEPT.md b/docs/CONCEPT.md new file mode 100644 index 0000000..9a6b190 --- /dev/null +++ b/docs/CONCEPT.md @@ -0,0 +1,163 @@ +# 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. + +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) + +## 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 + +The module does not own: + +- 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 +- 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. + +## 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 +- 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. diff --git a/docs/CONNECTOR_SOURCE_LIFECYCLE.md b/docs/CONNECTOR_SOURCE_LIFECYCLE.md new file mode 100644 index 0000000..b338b28 --- /dev/null +++ b/docs/CONNECTOR_SOURCE_LIFECYCLE.md @@ -0,0 +1,159 @@ +# Connector Source Lifecycle + +GovOPlaN modules should treat external systems as sources with explicit +lifecycle state. A connector profile can consume records from a source, publish +records into a source, or do both. The lifecycle below keeps connectors +predictable and avoids hidden module imports. + +## Source Directions + +- `consume`: GovOPlaN reads external records, normalizes them, and exposes them + to modules as external references, events, or staged imports. +- `publish`: GovOPlaN creates or updates external records and stores the external + identifiers as immutable references. +- `bidirectional`: GovOPlaN supports both directions with conflict detection and + reconciliation rules. + +## Source Data Lifecycle + +Connector profiles have operational states, while individual external records +or source datasets move through a data lifecycle: + +1. `discovered` + A source, record, file, feed item, webhook event, or remote object is known + but not yet trusted for domain use. +2. `connected` + GovOPlaN can authenticate and fetch or publish against the source profile. +3. `imported` + Minimal source data has been staged with external id, version/ETag, source + timestamp, and provenance. +4. `validated` + Shape, permissions, freshness, and required fields passed connector and + domain validation. +5. `transformed` + A dataflow, workflow, or domain module normalized the staged payload into a + domain-specific form. +6. `published` + GovOPlaN exposed or wrote an output through API, RSS, report, export, or a + downstream connector. +7. `archived` + The source/output is no longer active but remains available under retention, + audit, and external-reference rules. +8. `deprecated` + The source/output remains readable for history but must not be used for new + workflows. + +Every transition must preserve provenance, permissions context, freshness, and +audit trace. Domain modules may add stricter states, but they should map back to +this lifecycle when a connector publishes status. + +## Lifecycle States + +1. `draft` + Profile exists but is not used by runtime jobs. +2. `configured` + Required endpoint and credential references are present. +3. `tested` + A health/test run succeeded and recorded non-secret diagnostics. +4. `active` + Runtime jobs may consume or publish data. +5. `degraded` + The connector is active but health checks or recent jobs show failures. +6. `paused` + Operators intentionally stop scheduled connector activity. +7. `retiring` + The connector is being removed from active workflows while references remain + readable. +8. `retired` + No new runtime activity is allowed. Historical references remain available. + +## State Transition Gates + +| Transition | Required Evidence | Blockers | +| --- | --- | --- | +| `draft` -> `configured` | endpoint fields are valid, credential references exist, owner/tenant scope is set | plaintext secret in profile payload, unsupported connector type | +| `configured` -> `tested` | latest profile test succeeded and diagnostics were redacted | failed auth, unreachable endpoint, TLS/policy error | +| `tested` -> `active` | operator enabled runtime use, required modules/capabilities are present, schedule/webhook is valid | missing module, missing permission, no idempotency strategy for publish jobs | +| `active` -> `degraded` | health check or job telemetry reports failures | none; this is automatic diagnostic state | +| `degraded` -> `active` | health/test succeeds or failed jobs are reconciled | unresolved conflict or repeated failure threshold | +| any running state -> `paused` | operator pause request or maintenance preflight | active critical transaction that cannot be interrupted | +| `paused` -> `active` | successful re-test when credentials/endpoints changed | failed profile test | +| any state -> `retiring` | uninstall/disable plan accepted, schedulers/workers stopped | active domain references that require operator decision | +| `retiring` -> `retired` | non-destructive retirement complete, references remain readable | destructive retirement requested without provider and backup | + +## Consume Flow + +1. Discover changes through polling, webhook, batch upload, or manual operator + action. +2. Fetch only the minimal remote data required for the declared use case. +3. Normalize into a connector-owned staging payload. +4. Validate shape, required fields, and source trust level. +5. Emit a core-mediated event such as `connector.record_discovered`. +6. Let domain modules claim or transform staged data through capabilities, not + imports. +7. Store external references with source system, object type, object id, version + or ETag, and last-seen timestamp. + +## Publish Flow + +1. Domain module requests publish through a core-mediated connector capability. +2. Connector validates profile state, permission, idempotency key, and payload + shape. +3. Connector sends the remote request. +4. Connector stores the remote id, version/ETag, and response diagnostics. +5. Connector emits `connector.record_published` or `connector.publish_failed`. +6. Domain module stores only the external-reference DTO and any domain result. + +## Reconciliation + +Every connector that writes to an external system needs a reconciliation story: + +- idempotency key for create/update jobs +- remote object version, ETag, or last-modified value where available +- conflict state when local and remote records diverge +- retry policy for temporary failures +- explicit operator action for destructive overwrite or deletion +- audit trace from GovOPlaN record to external request and response summary + +## Capability Boundary + +Domain modules must not import connector implementation packages directly. They +should ask core for capabilities such as: + +- `connectors.catalog` +- `connectors.profileTester` +- `connectors.health` +- `connectors.externalReferences` +- `connectors.sourceConsumer` +- `connectors.sourcePublisher` + +Connector payloads should be DTOs or protocol objects from kernel/core +contracts. Protocol-specific clients stay inside the connector module that owns +them. + +## Safety Rules + +- Secret values never leave the secret contract and are never stored in test + result payloads. +- Runtime jobs must include profile id, connector type, direction, idempotency + key, and triggering principal/system actor. +- Profile tests must redact tokens, passwords, cookies, authorization headers, + and remote personal data not needed for diagnostics. +- Deactivation must stop schedulers/workers before profile removal. +- Uninstall defaults to non-destructive retirement; domain data and external + references remain readable. +- Destructive retirement requires a module-owned retirement provider and an + explicit operator choice. + +## Release Checklist + +Before shipping an executable connector type: + +- Add catalogue metadata and capability names. +- Add profile schema validation that rejects plaintext secrets. +- Add redaction tests for success and failure diagnostics. +- Add unavailable-optional-module tests for every consuming domain module. +- Add profile test and health status fixtures. +- Add external-reference DTO tests. +- Add lifecycle transition tests for pause, retry, retirement, and uninstall + guard behavior. diff --git a/docs/GOVERNED_CONNECTOR_CONFIGURATION.md b/docs/GOVERNED_CONNECTOR_CONFIGURATION.md new file mode 100644 index 0000000..8e95aa2 --- /dev/null +++ b/docs/GOVERNED_CONNECTOR_CONFIGURATION.md @@ -0,0 +1,48 @@ +# Governed Connector Configuration + +GovOPlaN connectors should make integration behavior inspectable and testable. +The target is not hardcoded glue hidden in module code, but governed connector +definitions with schemas, mappings, test runs, simulation, versioning, and +audit-visible execution. + +## Connector Definition + +A connector definition should describe: + +- provider type and protocol +- endpoint and credential requirements +- supported capabilities +- input and output schemas +- mapping and transformation versions +- validation rules +- dry-run and test operations +- privacy and retention classification +- expected events and audit records +- operational limits and retry behavior + +Provider-specific code may still be required, but the configured integration +logic should remain visible and reviewable. + +## Runtime Expectations + +Connectors should support: + +- discovery where possible +- typed configuration through UI-managed controls +- secret references instead of plaintext secrets +- dry-run plans before writes +- simulation with sample payloads +- provenance for consumed and produced data +- idempotent external writes where supported +- quarantine/manual-review state for unsafe or ambiguous results + +Configuration packages may install connector definitions, but local overrides +must be protected from accidental package updates. + +## Relationship To Datasources And Dataflow + +Recurring extraction and transformation should start as configuration across +connectors, files, workflow, reporting, and templates. Create dedicated +datasource or dataflow modules only when repeated source-catalog, lineage, +mapping, scheduling, or publication contracts clearly outgrow connector +ownership. diff --git a/docs/OPENDESK_INTEGRATION_MAP.md b/docs/OPENDESK_INTEGRATION_MAP.md new file mode 100644 index 0000000..8999405 --- /dev/null +++ b/docs/OPENDESK_INTEGRATION_MAP.md @@ -0,0 +1,71 @@ +# OpenDesk Integration Map + +OpenDesk is an integration profile across GovOPlaN modules, not a monolithic +GovOPlaN module. The profile should let an operator see which OpenDesk +components are connected, which GovOPlaN module owns each behavior, and which +optional capabilities are available. + +The core boundary decision register is in +`/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`. + +## Component Routing + +| OpenDesk area | Example component | GovOPlaN owner | Integration behavior | +| --- | --- | --- | --- | +| Identity and directory | OpenDesk IDM, LDAP, AD, OIDC, SAML, SCIM | `govoplan-idm`, `govoplan-access` | integrate, synchronize selected accounts/groups, map principals and memberships | +| Mail/groupware | Open-Xchange mail | `govoplan-mail` | integrate, link profiles, test mailbox/send/append, keep mail semantics in mail | +| Calendar/groupware | Open-Xchange calendar, CalDAV/CardDAV | `govoplan-calendar` | integrate, free/busy lookup, selected event sync, resource calendars | +| Files/documents | Nextcloud/WebDAV/files, office integrations | `govoplan-files`, later `govoplan-dms` | integrate, import/link files, keep document lifecycle in DMS | +| Project management | OpenProject | `govoplan-connectors`, consumers in tasks/workflow/cases | connector-first, link/synchronize selected work packages | +| Portal/collaboration | Portal/chat/video/office services where present | `govoplan-portal`, `govoplan-connectors`, `govoplan-dms`, `govoplan-workflow` | link/integrate only when a process needs it | +| Inventory and diagnostics | endpoint catalogue, profile health, version checks | `govoplan-connectors` | catalogue, profile test, health summary, optional capability discovery | + +## Integration Behavior + +- `integrate`: call a stable API or protocol for the component. +- `link`: store external references and open the external tool for + source-of-truth work. +- `import`: bring selected files/records into GovOPlaN-owned storage or + evidence. +- `synchronize`: keep selected records aligned through explicit source-of-truth + rules. +- `replace selected workflow`: only when GovOPlaN owns tighter governance, + audit, retention, or configuration-package state than the OpenDesk component. + +## Shared Assumptions + +- Identity is the first dependency. Mail, calendar, files, and project + connectors should record which identity profile or tenant mapping they expect. +- Connector profiles store references to secrets, never secret values. +- Module consumers discover optional behavior through core capabilities and + module metadata. +- The profile must work partially: an installation can have OpenProject without + Open-Xchange, or calendar without files. + +## Candidate Profile Shape + +```json +{ + "id": "opendesk-main", + "display_name": "OpenDesk", + "components": { + "identity": {"profile_id": "opendesk-idm", "owner": "govoplan-idm"}, + "mail": {"profile_id": "ox-mail", "owner": "govoplan-mail"}, + "calendar": {"profile_id": "ox-calendar", "owner": "govoplan-calendar"}, + "files": {"profile_id": "nextcloud-main", "owner": "govoplan-files"}, + "projects": {"profile_id": "openproject-main", "owner": "govoplan-connectors"} + } +} +``` + +## Follow-Up Implementation Issues + +Existing high-priority module issues: + +- `govoplan-idm#1`: LDAP, Active Directory, OpenDesk identity services. +- `govoplan-mail#5`: Open-Xchange mail/groupware adapter boundary. +- `govoplan-calendar#2`: Open-Xchange calendar adapter boundary. +- `govoplan-connectors#1`: OpenProject connector. + +Future executable connector issues should be created in the owning module +repository when the first concrete API/profile slice is selected. diff --git a/docs/OPENPROJECT_CONNECTOR.md b/docs/OPENPROJECT_CONNECTOR.md new file mode 100644 index 0000000..7cb9031 --- /dev/null +++ b/docs/OPENPROJECT_CONNECTOR.md @@ -0,0 +1,170 @@ +# OpenProject Connector Concept + +OpenProject is the first proposed concrete connector for +`govoplan-connectors`. It gives GovOPlaN a public-sector-friendly project and +work-package integration target without making project management a core +platform dependency. + +## Goals + +- Register OpenProject connection profiles. +- Test API reachability and authentication without exposing secrets. +- Read projects, users, statuses, and work packages for linking. +- Create or update work packages from GovOPlaN tasks/cases/workflows once those + modules request the capability. +- Receive or poll changes for external-reference synchronization. +- Keep all OpenProject-specific client code inside the connector module. + +## Non-Goals + +- Replacing a future native GovOPlaN project-management module. +- Importing workflow, tasks, cases, or access implementation modules directly. +- Mirroring complete OpenProject project state into GovOPlaN by default. +- Storing OpenProject tokens outside the platform secret contract. + +## Profile Fields + +Candidate profile payload: + +- `base_url` +- `api_version`, default `v3` +- `credential_ref` +- `verify_tls` +- `timeout_seconds` +- `allowed_project_ids` +- `default_project_id` +- `webhook_secret_ref`, optional +- `poll_interval_seconds`, optional + +## Health Check + +The connection test should: + +1. Normalize and validate `base_url`. +2. Resolve the credential reference. +3. Call the OpenProject API root or a small read-only endpoint. +4. Record API version, authenticated principal where available, latency, + response status, and safe capability hints. +5. Redact token, Authorization headers, cookies, and any server-provided secret + fields from diagnostics. + +## Candidate Capabilities + +- `connectors.openproject.profileTester` +- `connectors.openproject.projects` +- `connectors.openproject.workPackages.read` +- `connectors.openproject.workPackages.write` +- `connectors.openproject.webhooks` +- `connectors.openproject.externalReferences` + +Domain modules request these through core-mediated capabilities. For example, +`govoplan-tasks` can publish a task as an OpenProject work package without +importing OpenProject client code. + +## Data Boundary Decision + +OpenProject should be referenced live by default, not mirrored wholesale into +GovOPlaN. The connector stores stable external references and safe metadata: + +- profile id and connector type +- project id and work-package id +- external URL +- remote version, ETag, or lock version where available +- last-seen timestamp and safe status/type labels +- GovOPlaN trace id for publish or synchronization jobs + +GovOPlaN should import only the subset needed by a requesting domain module, +for example a work-package title/status for display, a link-back reference for a +task, or evidence that a publish operation succeeded. Full project state, +comments, attachments, membership lists, and custom fields remain remote unless +a future domain module explicitly owns that synchronization. This keeps cases, +tasks, workflow, and reporting decoupled from OpenProject while still allowing +link-out, link-back, selected publish, and selected read views. + +## Runtime Events + +- `openproject.profile_tested` +- `openproject.project_seen` +- `openproject.work_package_seen` +- `openproject.work_package_published` +- `openproject.webhook_received` +- `openproject.sync_failed` + +Events should carry GovOPlaN ids, external ids, safe diagnostics, and trace +context. They must not contain credentials or raw personal data beyond what the +requesting domain module is authorized to process. + +## Webhook And Polling Strategy + +OpenProject supports API and webhook administration. The connector should allow +both: + +- Webhook-first when an operator registers a webhook for selected project/work + package events. +- Polling fallback for installations where webhooks cannot be exposed. + +The first implementation can start with manual test plus read-only project/work +package lookup, then add publishing, then webhook/polling synchronization. + +## First Implementation Slice + +1. Add connector type metadata for `openproject`. +2. Add connection profile CRUD using secret references. +3. Add a read-only test endpoint. +4. Add project/work-package lookup DTOs. +5. Add external-reference storage for linked OpenProject work packages. +6. Add a WebUI profile page with last-test diagnostics. +7. Add tests for redaction, unavailable connector behavior, and optional module + capability discovery. + +## Minimum DTOs + +Profile summary: + +```json +{ + "id": "openproject-main", + "connector_type": "openproject", + "name": "OpenProject", + "base_url": "https://openproject.example", + "state": "tested", + "last_test_at": "2026-07-09T10:00:00Z", + "last_test_status": "success" +} +``` + +External reference: + +```json +{ + "connector_type": "openproject", + "profile_id": "openproject-main", + "object_type": "work_package", + "external_id": "1234", + "external_url": "https://openproject.example/work_packages/1234", + "version": "etag-or-lock-version", + "metadata": { + "project_id": "42" + } +} +``` + +Diagnostics must be redacted and should include only endpoint, version, +authenticated principal label where safe, latency, status code, and capability +hints. + +## First Tests To Add + +- profile create/update rejects plaintext token fields +- profile test redacts Authorization, cookies, and token-like response fields +- lookup capabilities are absent when the connector module is disabled +- a task/workflow/case module can detect OpenProject capabilities without + importing connector internals +- external-reference round-trip stores profile id, object type, external id, + version/ETag, URL, and safe metadata + +## Reference Sources + +- OpenProject API v3 documentation: https://www.openproject.org/docs/api/ +- OpenProject API introduction: https://www.openproject.org/docs/api/introduction/ +- OpenProject API and webhooks administration: https://www.openproject.org/docs/system-admin-guide/api-and-webhooks/ diff --git a/docs/PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md b/docs/PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md new file mode 100644 index 0000000..59d1957 --- /dev/null +++ b/docs/PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md @@ -0,0 +1,156 @@ +# Public-Sector Integration Catalogue + +`govoplan-connectors` should maintain an operator-visible catalogue of common +external systems, protocols, and integration patterns. The catalogue is not a +promise that GovOPlaN replaces those systems. It is the map that lets modules +discover what exists, test connections, and decide which optional behavior can +be enabled. + +## Catalogue Entry Shape + +Each connector type should define: + +- stable connector type key, for example `openproject`, `fit-connect`, + `xrepository`, or `sap` +- category and owning GovOPlaN module, if any +- supported direction: consume, publish, or bidirectional +- supported trigger modes: manual test, polling, webhook, batch import, export +- credential method and whether secrets are stored through the platform secret + contract +- health check and diagnostic payload shape +- external reference shape for records created or linked through the connector +- required capabilities and optional module combinations +- lifecycle support: activate, pause, re-test, rotate credential, retire + +## Initial Target Categories + +The catalogue should be maintained as a ranked inventory. A target can start as +an inventory entry before there is executable connector code. + +| Target | Scope/Jurisdiction | Category | Mode | Likely Owner | First Useful Capability | Priority | +| --- | --- | --- | --- | --- | --- | --- | +| OpenProject | international/open source | Project/task management | link, synchronize selected records, publish tasks | `govoplan-connectors`, later tasks/workflow/projects | profile test, project/work-package lookup, external references | Wave 0 | +| Nextcloud/WebDAV/SMB/Seafile | broad public-sector/self-hosted | File providers | integrate, import, link | `govoplan-files` with connector inventory | profile health and managed-file provenance | Wave 0/in progress | +| OpenDesk IDM, LDAP, Active Directory, OIDC, SAML | Germany/EU and general enterprise | Identity | integrate, synchronize | `govoplan-idm`, `govoplan-access` | endpoint inventory, login/provisioning preflight | Wave 1 | +| Open-Xchange mail/calendar | Germany/OpenDesk and groupware deployments | Groupware | integrate, link | `govoplan-mail`, `govoplan-calendar` | profile test, mailbox/calendar diagnostics | Wave 1 | +| FIT-Connect | German public-sector transport | Public-sector transport | integrate, publish, receive | dedicated protocol module with connectors inventory | destination profile, test, receipt reference | Wave 1 | +| XRepository/XÖV lookup | German public-sector standards | Standards registry | link, import schema metadata | `govoplan-connectors`, later XÖV modules | read-only catalogue lookup/cache | Wave 1 | +| RSS/API publication | public data/external services | Publication/data exchange | consume, publish | `govoplan-connectors`, `govoplan-dataflow` | consume/publish feed profiles | Wave 2 | +| DMS/e-file/archive systems | German municipal/state/federal administration | DMS/records | link, import, synchronize selected metadata | `govoplan-dms`, `govoplan-files` | external document reference and health | Wave 2 | +| ERP/finance/procurement/payment systems | German municipal finance/procurement plus EU standards | ERP/payment | export, import, synchronize, replace only by domain decision | dedicated modules | profile inventory and export/import staging | Wave 2 | + +### Project And Task Management + +- OpenProject +- Jira or Jira-compatible APIs +- Redmine +- Microsoft Planner/Project where available through Microsoft Graph + +GovOPlaN should start with OpenProject because it is open source, common in +public-sector environments, and has API/webhook documentation suitable for a +first connector. + +### DMS, E-File, Records, And Archive + +- d.velop/d.3 +- enaio +- Fabasoft eGov-Suite +- ELO +- VIS/eAkte environments +- CMIS-capable repositories +- S3/object storage used as archive staging + +These targets should usually be owned by DMS/files/records modules once a +domain module exists. `govoplan-connectors` should still provide inventory, +profiles, and generic health checks. + +### File Providers + +- SMB/CIFS +- WebDAV +- Nextcloud +- Seafile +- S3-compatible object storage +- SFTP + +The files module owns file semantics. The connectors catalogue should record +profile metadata and health, but must not import files-module internals. + +### Identity And Access + +- LDAP +- Active Directory +- OIDC +- SAML +- OpenDesk IDM and comparable identity platforms + +The access/IDM modules own principal synchronization and authorization effects. +Connectors own endpoint inventory and diagnostics. + +### Mail, Calendar, And Collaboration + +- Microsoft Exchange/M365 +- Open-Xchange +- IMAP/SMTP where represented as external infrastructure +- CalDAV/CardDAV +- chat, video, and collaboration systems such as Matrix, Jitsi, BigBlueButton, + Nextcloud Talk, or Collabora/OnlyOffice environments + +Mail/calendar/collaboration modules own business semantics. Connector profiles +can expose reachability and version diagnostics. + +### ERP, Finance, Procurement, And Payment + +- SAP +- MACH +- Infoma/new system +- DATEV interfaces +- XRechnung/Peppol access points +- XBestellung and procurement feeds +- payment providers and cash-register systems + +Protocol-heavy parts should move into dedicated modules such as +`govoplan-xrechnung`, `govoplan-erp`, `govoplan-procurement`, or +`govoplan-payments`. + +### Public-Sector Protocols And Registries + +- FIT-Connect +- XTA/OSCI +- XÖV standards and XRepository lookup +- XRechnung/XBestellung +- register and Fachverfahren interfaces discovered by implementation projects + +These are integration priorities because they model common administrative +processes. They should be represented as connector categories even when a +dedicated module later owns the actual protocol implementation. + +## Wave 0 Catalogue Priorities + +1. OpenProject connector concept and profile shape. +2. Generic connector profile, health, and secret-reference model. +3. Public-sector target inventory table with category, owner module, and + priority. +4. Consume/publish source lifecycle contract. +5. External-reference DTO shared through kernel/core contracts. +6. Configuration-package declaration for required connector profiles. + +## Catalogue Maintenance Rules + +- Prefer one stable connector type key per external product or protocol family. +- Record when GovOPlaN should integrate with an existing product instead of + replacing it. +- Keep protocol/client implementation in the owning connector or protocol + module; domain modules consume capabilities and DTOs only. +- Treat "inventory only" entries as useful: operators can document a landscape + before GovOPlaN can automate it. +- Every executable connector type needs a redaction-safe test plan, lifecycle + states, external-reference shape, and uninstall/retirement behavior. + +## Reference Sources + +- OpenProject API v3 documentation: https://www.openproject.org/docs/api/ +- OpenProject API and webhooks administration: https://www.openproject.org/docs/system-admin-guide/api-and-webhooks/ +- FIT-Connect Destination API documentation: https://docs.fitko.de/en/resources/fit-connect-destination-api/ +- XÖV overview by KoSIT: https://www.xoev.de/xoev-4987 +- XRepository overview: https://www.xrepository.de/