add-ideas/govoplan-connectors
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
govoplan-connectors/docs/OPENPROJECT_CONNECTOR.md

5.8 KiB
Raw Permalink Blame History

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:

{
  "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:

{
  "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