GovOPlaN/govoplan-connectors
2
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

Release Connectors v0.1.22 with service-desk federation
Module Package Release / publish-packages (push) Successful in 12s
Details

Browse Source
This commit is contained in:
zemion
2026-08-22 16:11:07 +02:00
parent 79e2315e89
commit b277e8d7ac
22 changed files with 7348 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/govoplan_connectors/backend/manifest.py
+239 -6
View File
@@ -50,6 +50,9 @@ from govoplan_connectors.backend.db.models import (
ConnectorKnowledgeObject,
ConnectorKnowledgeProfile,
ConnectorKnowledgeSyncRun,
ConnectorServiceDeskObject,
ConnectorServiceDeskProfile,
ConnectorServiceDeskSyncRun,
ConnectorSanctionsAcquisitionRun,
ConnectorSanctionsSnapshot,
ConnectorSimulationRun,
@@ -69,6 +72,19 @@ from govoplan_connectors.backend.knowledge_connector import (
from govoplan_connectors.backend.knowledge_search import (
create_external_knowledge_search_source,
)
from govoplan_connectors.backend.service_desk_connector import (
SERVICE_DESK_ADMIN_SCOPE,
SERVICE_DESK_CAPABILITY,
SERVICE_DESK_INTERFACE_VERSION,
SERVICE_DESK_PROVIDER_ID,
SERVICE_DESK_READ_SCOPE,
SERVICE_DESK_SYNC_SCOPE,
SERVICE_DESK_UPDATE_SCOPE,
ExternalServiceDeskCapability,
)
from govoplan_connectors.backend.service_desk_search import (
create_external_service_desk_search_source,
)
from govoplan_connectors.backend.dsar_provider import (
CONNECTORS_DSAR_CAPABILITY,
ConnectorsDsarProvider,
@@ -97,12 +113,13 @@ from govoplan_connectors.backend.provider_state import (
TABULAR_PROVIDER_ID,
knowledge_provider_states,
sanctions_provider_states,
service_desk_provider_states,
tabular_provider_states,
)
MODULE_ID = "connectors"
MODULE_VERSION = "0.1.21"
MODULE_VERSION = "0.1.22"
TABULAR_SOURCE_INTERFACE_VERSION = "0.1.0"
DATASOURCE_ORIGIN_INTERFACE_VERSION = "0.1.0"
SANCTIONS_SNAPSHOT_INTERFACE_VERSION = "1.0.0"
@@ -149,6 +166,11 @@ ARCHITECTURE = ModuleArchitectureDeclaration(
reference="tests/test_mediawiki_connector.py",
summary="Exercises deterministic MediaWiki/BlueSpice discovery, stable mapping, bounded deltas, ACL-safe Search, migration loss diagnostics, and publication recovery states.",
),
ModuleMaturityEvidence(
kind="test",
reference="tests/test_service_desk_connector.py",
summary="Exercises Znuny/OTRS profile policy, stable ticket mapping, bounded synchronization, Search authorization, governed updates, and unknown-outcome evidence.",
),
ModuleMaturityEvidence(
kind="documentation",
reference="docs/CONNECTOR_SOURCE_LIFECYCLE.md",
@@ -158,8 +180,9 @@ ARCHITECTURE = ModuleArchitectureDeclaration(
known_limits=(
"Tabular origins support immutable snapshots, exact managed CSV/XLSX versions, and read-only PostgreSQL tables; arbitrary REST and other database adapters remain future providers.",
"Feed publication renders a governed document but does not yet push it to an external publishing endpoint.",
"The MediaWiki/BlueSpice adapter publishes revision-checked page edits; generic simulations and all other providers do not imply a live write capability.",
"MediaWiki/BlueSpice publication and governed-sync Znuny/OTRS ticket updates are explicit revision-checked write paths; generic simulations and other providers do not imply a live write capability.",
"Migration into native Wiki is preview-only; a target-side write worker and Wiki-owned mutation contract remain future work.",
"The Znuny/OTRS GenericInterface route map is deployment-defined; queues must be partitioned below the 10000-ticket identity bound and attachment bytes remain provider-side.",
),
supported_authority_modes=(
"external_authoritative",
@@ -173,6 +196,7 @@ ARCHITECTURE = ModuleArchitectureDeclaration(
"immutable connector snapshots",
"connector acquisition health",
"external knowledge synchronization evidence",
"external service-desk transport and synchronization evidence",
),
non_owned_concepts=(
"datasource catalogue identity and lifecycle",
@@ -180,29 +204,35 @@ ARCHITECTURE = ModuleArchitectureDeclaration(
"data transformations",
"screening dispositions",
"native Wiki spaces, pages, and revision semantics",
"ticket, article, customer, case, and helpdesk business semantics",
),
target_tested_providers=(
TABULAR_PROVIDER_ID,
SANCTIONS_PROVIDER_ID,
KNOWLEDGE_PROVIDER_ID,
SERVICE_DESK_PROVIDER_ID,
),
documentation=ModuleArchitectureDocumentation(
migration=("src/govoplan_connectors/backend/migrations/versions",),
upgrade=(
"docs/CONNECTOR_SOURCE_LIFECYCLE.md",
"docs/MEDIAWIKI_BLUESPICE_CONNECTOR.md",
"docs/ZNUNY_OTRS_CONNECTOR.md",
),
recovery=(
"docs/CONNECTOR_SOURCE_LIFECYCLE.md",
"docs/MEDIAWIKI_BLUESPICE_CONNECTOR.md",
"docs/ZNUNY_OTRS_CONNECTOR.md",
),
security=(
"docs/CONNECTOR_SOURCE_LIFECYCLE.md",
"docs/MEDIAWIKI_BLUESPICE_CONNECTOR.md",
"docs/ZNUNY_OTRS_CONNECTOR.md",
),
operations=(
"docs/CONNECTOR_SOURCE_LIFECYCLE.md",
"docs/MEDIAWIKI_BLUESPICE_CONNECTOR.md",
"docs/ZNUNY_OTRS_CONNECTOR.md",
),
),
)
@@ -384,6 +414,77 @@ EXTERNAL_PROVIDERS = (
"connectors.mediawiki-bluespice",
),
),
ExternalProviderDeclaration(
id=SERVICE_DESK_PROVIDER_ID,
module_id=MODULE_ID,
label="Znuny and OTRS-compatible service-desk provider",
maturity="synchronize",
operations=("discover", "link", "search", "read", "publish", "synchronize"),
objects=(
ProviderObjectDeclaration(
object_type="external_service_desk_ticket",
field_groups=(
"stable_identity",
"queue_and_routing",
"state_and_priority",
"users_and_organizations",
"articles",
"attachment_metadata",
"dynamic_fields",
"permissions",
"source_provenance",
),
authority_modes=(
"external_authoritative",
"external_mirror",
"governed_sync",
"linked_reference",
),
default_authority_mode="external_authoritative",
),
),
behavior=ProviderBehaviorDeclaration(
revision_tokens="Stable ticket, ticket-number, article, and attachment identities plus provider change timestamps, discovery revisions, cursors, and content hashes are retained.",
concurrency="Profiles use optimistic revisions; governed ticket updates require the synchronized provider revision and a durable idempotency fence.",
freshness="Discovery time, synchronization high-watermark, cursor, provider change time, observation time, and profile health remain explicit.",
health="Product/version verification, authentication, transport, route policy, mapping loss, ACL fallback, Search deferral, cursor bounds, and unknown update outcomes are explicit without exposing credentials.",
max_read_items=500,
idempotency="Every full, delta, or update operation requires a profile-wide caller key; exact replays return committed evidence and mismatched reuse is rejected.",
retry="Discovery and read-only synchronization can be retried deliberately; an update with an unknown outcome must be reconciled against the provider before retry.",
timeout_seconds=20,
conflicts="Queue inclusion, target refs, ACLs, dynamic fields, authority, and route mappings are explicit; updates reject stale provider revisions.",
outcome_unknown="A timed-out or inconclusive remote update remains outcome-unknown behind durable recovery evidence until an operator verifies the provider ticket revision.",
outcome_unknown_supported=True,
evidence="Mapped tickets retain stable external references, revisions, transport and mapping provenance, current ACLs, loss diagnostics, and operation effects; attachment bytes are never retained.",
audit_event_types=(
"connectors.service_desk.profile.created",
"connectors.service_desk.profile.updated",
"connectors.service_desk.profile.discovered",
"connectors.service_desk.profile.synchronized",
"connectors.service_desk.ticket.updated",
),
correction="A later provider revision updates or restores the connector projection while prior synchronization and mutation evidence stays retained.",
rollback="Local projection and terminal recovery evidence commit atomically; a remote provider update cannot be rolled back by a local transaction.",
reconciliation="Rediscover the deployment-defined GenericInterface routes, compare stable ticket revisions, finish or restart bounded synchronization, and inspect unresolved remote mutations.",
outage="Authorized existing projections remain visible with explicit stale health; no provider freshness or write-success claim is made during an outage.",
classifications=("internal", "confidential", "restricted"),
purposes=(
"external service-desk discovery",
"authorized federated search",
"ticket reference or import",
"bounded synchronization",
"governed ticket update",
),
retention="The tenant's connector, Tickets, Helpdesk, Cases, and Records policies determine projection and operation-evidence retention.",
secret_handling="Credentials resolve from a scoped Core envelope and use approved headers or POST bodies; they never enter GET URLs, snapshots, diagnostics, or API responses.",
),
capability_names=(SERVICE_DESK_CAPABILITY,),
interface_names=(SERVICE_DESK_CAPABILITY,),
documentation_topic_ids=(
"connectors.authority-and-effects",
"connectors.znuny-otrs",
),
),
)
@@ -462,6 +563,26 @@ PERMISSIONS = (
"Preview knowledge migration",
"Dry-run a bounded migration into Wiki and inspect loss or conflict diagnostics.",
),
_permission(
SERVICE_DESK_READ_SCOPE,
"View external service-desk tickets",
"View authorized Znuny/OTRS profiles, mapped tickets, and synchronization evidence.",
),
_permission(
SERVICE_DESK_ADMIN_SCOPE,
"Administer service-desk connectors",
"Configure GenericInterface routes, queues, fields, authority, visibility, and discovery.",
),
_permission(
SERVICE_DESK_SYNC_SCOPE,
"Synchronize service-desk tickets",
"Run bounded Znuny/OTRS backfills and change synchronization.",
),
_permission(
SERVICE_DESK_UPDATE_SCOPE,
"Update external service-desk tickets",
"Apply governed revision-checked ticket updates with durable recovery evidence.",
),
)
ROLE_TEMPLATES = (
@@ -482,6 +603,10 @@ ROLE_TEMPLATES = (
KNOWLEDGE_SYNC_SCOPE,
KNOWLEDGE_PUBLISH_SCOPE,
KNOWLEDGE_MIGRATE_SCOPE,
SERVICE_DESK_READ_SCOPE,
SERVICE_DESK_ADMIN_SCOPE,
SERVICE_DESK_SYNC_SCOPE,
SERVICE_DESK_UPDATE_SCOPE,
),
),
RoleTemplate(
@@ -497,13 +622,20 @@ ROLE_TEMPLATES = (
KNOWLEDGE_READ_SCOPE,
KNOWLEDGE_SYNC_SCOPE,
KNOWLEDGE_MIGRATE_SCOPE,
SERVICE_DESK_READ_SCOPE,
SERVICE_DESK_SYNC_SCOPE,
),
),
RoleTemplate(
slug="connector_source_reader",
name="Connector source reader",
description="Discover and preview tabular connector sources.",
permissions=(READ_SCOPE, SANCTIONS_READ_SCOPE, KNOWLEDGE_READ_SCOPE),
permissions=(
READ_SCOPE,
SANCTIONS_READ_SCOPE,
KNOWLEDGE_READ_SCOPE,
SERVICE_DESK_READ_SCOPE,
),
),
)
@@ -542,6 +674,10 @@ def _knowledge_provider(_context) -> ExternalKnowledgeCapability:
return ExternalKnowledgeCapability()
def _service_desk_provider(_context) -> ExternalServiceDeskCapability:
return ExternalServiceDeskCapability()
def _tenant_summary(session, tenant_id: str) -> dict[str, int]:
return {
"connector_definitions": (
@@ -595,6 +731,24 @@ def _tenant_summary(session, tenant_id: str) -> dict[str, int]:
.filter(ConnectorKnowledgeSyncRun.tenant_id == tenant_id)
.count()
),
"connector_service_desk_profiles": (
session.query(ConnectorServiceDeskProfile)
.filter(ConnectorServiceDeskProfile.tenant_id == tenant_id)
.count()
),
"connector_service_desk_objects": (
session.query(ConnectorServiceDeskObject)
.filter(
ConnectorServiceDeskObject.tenant_id == tenant_id,
ConnectorServiceDeskObject.status != "deleted",
)
.count()
),
"connector_service_desk_runs": (
session.query(ConnectorServiceDeskSyncRun)
.filter(ConnectorServiceDeskSyncRun.tenant_id == tenant_id)
.count()
),
}
@@ -612,6 +766,9 @@ manifest = ModuleManifest(
"reporting",
"risk_compliance",
"search",
"tickets",
"helpdesk",
"cases",
"wiki",
),
required_capabilities=(
@@ -647,6 +804,10 @@ manifest = ModuleManifest(
name=KNOWLEDGE_CAPABILITY,
version=KNOWLEDGE_INTERFACE_VERSION,
),
ModuleInterfaceProvider(
name=SERVICE_DESK_CAPABILITY,
version=SERVICE_DESK_INTERFACE_VERSION,
),
ModuleInterfaceProvider(name=CONNECTORS_DSAR_CAPABILITY, version="0.1.0"),
),
requires_interfaces=(
@@ -687,6 +848,14 @@ manifest = ModuleManifest(
parent_id="connectors.admin.governed-configurations",
order=30,
),
ViewSurface(
id="connectors.admin.external-service-desk",
module_id=MODULE_ID,
kind="section",
label="External service desk",
parent_id="connectors.admin.governed-configurations",
order=40,
),
),
),
capability_factories={
@@ -696,6 +865,7 @@ manifest = ModuleManifest(
CAPABILITY_CONNECTORS_SANCTIONS_SNAPSHOTS: (_sanctions_snapshot_provider),
CAPABILITY_CONNECTORS_FEEDS: _feed_provider,
KNOWLEDGE_CAPABILITY: _knowledge_provider,
SERVICE_DESK_CAPABILITY: _service_desk_provider,
CONNECTORS_DSAR_CAPABILITY: _dsar_provider,
},
capability_documentation={
@@ -715,6 +885,11 @@ manifest = ModuleManifest(
factory=create_external_knowledge_search_source,
order=65,
),
SearchSourceProviderRegistration(
id=SERVICE_DESK_PROVIDER_ID,
factory=create_external_service_desk_search_source,
order=66,
),
),
architecture=ARCHITECTURE,
external_providers=EXTERNAL_PROVIDERS,
@@ -734,6 +909,11 @@ manifest = ModuleManifest(
provider_id=KNOWLEDGE_PROVIDER_ID,
provider=knowledge_provider_states,
),
ExternalProviderStateProviderRegistration(
module_id=MODULE_ID,
provider_id=SERVICE_DESK_PROVIDER_ID,
provider=service_desk_provider_states,
),
),
migration_spec=MigrationSpec(
module_id=MODULE_ID,
@@ -741,6 +921,9 @@ manifest = ModuleManifest(
script_location=str(Path(__file__).with_name("migrations") / "versions"),
retirement_supported=True,
retirement_provider=drop_table_retirement_provider(
ConnectorServiceDeskSyncRun,
ConnectorServiceDeskObject,
ConnectorServiceDeskProfile,
ConnectorKnowledgeSyncRun,
ConnectorKnowledgeObject,
ConnectorKnowledgeProfile,
@@ -760,6 +943,9 @@ manifest = ModuleManifest(
),
uninstall_guard_providers=(
persistent_table_uninstall_guard(
ConnectorServiceDeskSyncRun,
ConnectorServiceDeskObject,
ConnectorServiceDeskProfile,
ConnectorKnowledgeSyncRun,
ConnectorKnowledgeObject,
ConnectorKnowledgeProfile,
@@ -784,9 +970,9 @@ manifest = ModuleManifest(
body=(
"Connectors correlates only an exact tenant account identifier and can "
"narrow an already verified search to one source, acquisition, "
"definition, configuration, simulation, external-knowledge profile, or "
"knowledge operation. The export identifies the subject's configuration, "
"acquisition, simulation, knowledge-operation, and review activity "
"definition, configuration, simulation, external-knowledge or service-desk "
"profile, or connector operation. The export identifies the subject's "
"configuration, acquisition, simulation, external-operation, and review activity "
"using bounded lifecycle metadata. It never includes credential or "
"endpoint references, source rows, external responses, request payloads, "
"mapping and configuration documents, diagnostics, provenance, hashes, "
@@ -985,6 +1171,53 @@ manifest = ModuleManifest(
related_modules=("risk_compliance", "dataflow"),
order=41,
),
DocumentationTopic(
id="connectors.znuny-otrs",
title="Connect Znuny and OTRS-compatible service desks",
summary="Link, import, synchronize, search, and govern updates to external tickets without collapsing Tickets, Helpdesk, or Cases semantics.",
body=(
"A connector administrator first creates an active governed configuration for a Znuny or OTRS-compatible GenericInterface REST endpoint and keeps credentials in a scoped Core credential envelope. Because GenericInterface route paths and methods are defined by each provider deployment, the service-desk profile explicitly maps search, ticket-read, optional update, and browser-link routes. The profile chooses link, snapshot import, or ongoing synchronization; separately it records external, mirror, linked-reference, or governed-sync authority. Queue mappings decide inclusion, optional target queue references, and current tenant or restricted ACLs. Dynamic-field mappings declare included fields, governed names, and value types. Discovery verifies endpoint health, the exact configuration revision, product/version evidence, and safe technical maturity. A changed endpoint, governed configuration, or route map invalidates discovery and prior projections: synchronization and updates require rediscovery, while Search stays closed until a new full reconciliation. Integration or mapping changes also reset the cursor for a full reconciliation. A bounded full run reconciles stable ticket identities, then synchronize mode changes to cursor-based, revision-aware deltas with overlap-safe provider timestamps; delta cannot bootstrap an unreconciled profile, and supplied cursors must match committed state. The connector maps queues, state, priority, type, owners, responsible users, customers, organizations, services, SLAs, articles, attachment metadata, dynamic fields, provenance, and structured loss diagnostics. It never retains attachment bytes. GenericInterface has no portable standard ticket ACL, so provider-supplied GovOPlaN ACL metadata wins when present; otherwise reviewed queue or restricted profile defaults apply. Search includes only active authorized projections and rechecks tenant, profile status, read scope, current configuration discovery, and current ACL for every result. A ticket remains an external ticket reference: creating or relating a GovOPlaN Ticket, Helpdesk item, or Case belongs to those modules. Remote updates are available only in governed-sync mode after discovery confirms an update route, require the synchronized external revision and a unique idempotency key, and retain durable outcome evidence. If the result is unknown, operators must inspect the provider revision before retry. Providers with more than 10000 identities must be partitioned into queue-scoped profiles; too many tickets at one timestamp also require narrower partitions. During outages, existing authorized projections remain visibly stale and never imply current provider state."
),
layer="configured",
documentation_types=("admin", "user"),
audience=(
"operator",
"module_admin",
"integration_admin",
"service_desk_manager",
"auditor",
),
related_modules=(
"core",
"search",
"tickets",
"helpdesk",
"cases",
"audit",
"policy",
),
order=44,
translations={
"de": {
"title": "Znuny- und OTRS-kompatible Service-Desks anbinden",
"summary": "Externe Tickets verknüpfen, importieren, synchronisieren, durchsuchen und gesteuert aktualisieren, ohne die Fachsemantik von Tickets, Helpdesk oder Cases zu vermischen.",
"body": (
"Die Connector-Administration erstellt zuerst eine aktive, gesteuerte Konfiguration für einen Znuny- oder OTRS-kompatiblen GenericInterface-REST-Endpunkt; Zugangsdaten bleiben in einem zweckgebundenen Core-Umschlag. Da Pfade und Methoden im GenericInterface je Installation festgelegt werden, ordnet das Service-Desk-Profil Suche, Ticketabruf, optionale Aktualisierung und Browserlink ausdrücklich zu. Das Profil wählt Verknüpfung, Snapshot-Import oder fortlaufende Synchronisierung und legt getrennt davon Quellhoheit, Spiegelung, Referenz oder gesteuerte beidseitige Aktualisierung fest. Warteschlangen-Zuordnungen bestimmen Einschluss, optionale Zielreferenz und aktuelle mandantenweite oder eingeschränkte ACLs. Dynamische Felder erhalten freigegebene Namen und Datentypen. Die Erkennung prüft Gesundheit, die genaue Konfigurationsrevision, Produkt-/Versionsnachweis und technische Reife. Ein geänderter Endpunkt, eine geänderte gesteuerte Konfiguration oder Routenabbildung macht Nachweis und bisherige Projektionen ungültig; Synchronisierung und Aktualisierungen erfordern erneute Erkennung, Search zusätzlich einen neuen Vollabgleich. Änderungen an Integration oder Abbildungen setzen den Cursor ebenfalls zurück. Erst nach einem begrenzten Vollabgleich verwendet der Synchronisierungsmodus revisionsbewusste, überlappungssichere Delta-Cursor; Delta kann kein unabgeglichenes Profil initialisieren und übergebene Cursor müssen dem gespeicherten Stand entsprechen. Abgebildet werden stabile Ticket-, Artikel- und Anhangskennungen, Warteschlange, Status, Priorität, Typ, Bearbeitende, Kundschaft, Organisationen, Services, SLAs, Artikel, Anhangsmetadaten, dynamische Felder, Herkunft und Verlustdiagnosen. Anhangsdaten werden nie gespeichert. Da das Standard-GenericInterface keine portable Ticket-ACL liefert, haben ausdrücklich gelieferte GovOPlaN-ACL-Metadaten Vorrang; sonst greifen geprüfte Warteschlangen- oder eingeschränkte Profilvorgaben. Search prüft bei jedem Treffer Mandant, Profilstatus, Leserecht, aktuellen Konfigurationsnachweis und aktuelle ACL neu. Ein externes Ticket bleibt eine externe Referenz; fachliche Tickets, Helpdesk-Vorgänge und Cases werden ausschließlich von den jeweiligen Modulen erzeugt oder verknüpft. Externe Änderungen sind nur im Modus der gesteuerten Synchronisierung mit erkannter Update-Route, erwarteter Quellrevision und eindeutigem Idempotenzschlüssel zulässig. Ein unbekanntes Ergebnis muss vor einem erneuten Versuch am Anbieter geprüft werden. Profile mit mehr als 10000 Ticketkennungen oder zu vielen Änderungen am selben Zeitstempel müssen nach Warteschlangen enger aufgeteilt werden. Bei einem Ausfall bleiben bestehende Projektionen nur für weiterhin Berechtigte und mit sichtbarer veralteter Gesundheit verfügbar."
),
}
},
metadata={
"kind": "guide",
"help_contexts": ["connectors.admin.external-service-desk"],
"prerequisites": [
"An active governed Znuny/OTRS GenericInterface REST configuration exists.",
"Deployment-defined routes, queue partitions, authority, and fallback ACLs have been reviewed.",
"Tickets, Helpdesk, Cases, and Search remain optional capability-separated consumers.",
],
"outcome": "External tickets remain identity-stable, loss-visible, ACL-safe, recoverable, and semantically separate from GovOPlaN domain records.",
"verification": "Rediscover the profile, finish a keyed full run, run a keyed delta, inspect mapping diagnostics, verify one allowed and denied Search principal, and reconcile every outcome-unknown update before retry.",
},
),
),
)