2.0 KiB
External References And Integration Maturity
GovOPlaN integrations use a shared external-reference contract instead of storing connector-specific URLs and identifiers in every module.
An external reference identifies an object by:
- external system instance
- object type
- stable external object ID
- optional connector configuration
- canonical HTTP(S) URL without embedded credentials
- optional source version, ETag, observation time, and non-secret metadata
The identity key is system:object_type:object_id. A GovOPlaN object may retain
multiple references, but one reference must never silently change its identity.
Moving or escalating work creates a new object and an explicit relationship; it
does not rewrite either object's history.
Integration Maturity
Maturity is cumulative:
discover: identify configured external systems and their health.link: retain and open stable external references.search: include authorized external objects in GovOPlaN search.read: display authoritative external content.publish: create or update external content from GovOPlaN.synchronize: reconcile changes in both directions with conflict handling.migrate: perform a governed, verifiable transfer into GovOPlaN.replace: provide the native operational capability without the external tool.
Connectors must declare and document the maturity they actually implement.
synchronize requires durable cursors, idempotency, provenance, conflict
handling, deletion semantics, and observable failures. A link-only connector
must not imply that GovOPlaN holds an authoritative copy.
Domain Ownership
- Domain modules own native GovOPlaN objects and their authorization.
- Connectors own protocols, credentials, discovery, transport, and sync state.
- Search owns indexing and result aggregation, but source modules remain responsible for authorization.
- Core owns only the stable DTOs and extension contracts.
The Python contract is
govoplan_core.core.external_references.ExternalObjectReference.