chore: sync GovOPlaN module split state
This commit is contained in:
170
docs/OPENPROJECT_CONNECTOR.md
Normal file
170
docs/OPENPROJECT_CONNECTOR.md
Normal file
@@ -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/
|
||||
Reference in New Issue
Block a user