Zum Inhalt springen
Znuny Logo Znuny Community Docs

Plugin-Entwicklung mit OPM-Paketen

In diesem Abschnitt lernst du, wie du eigene Plugins als OPM-Pakete für Znuny erstellst, installierst und verteilst.

Abschnitt betitelt „In diesem Abschnitt lernst du, wie du eigene Plugins als OPM-Pakete für Znuny erstellst, installierst und verteilst.“

1. Aufbau einer .sopm

Abschnitt betitelt „1. Aufbau einer .sopm“

Die SOPM-Datei (*.sopm) enthält alle Metadaten deines Pakets: `.sopm“

  • Name/Version/Framework: Eindeutige Paketkennung und kompatible Znuny-Version.
  • Filelist: Alle Dateien, die beim Installieren kopiert werden.

2. Dateien & Verzeichnisstruktur

Abschnitt betitelt „2. Dateien & Verzeichnisstruktur“

Lege dein Paket in einem eigenen Verzeichnis an, z.B. MyExtension/: *.sopm

  • Kernel/Config/Files/XML/: Registriert Module, Menüs oder Dynamic Fields.
  • Kernel/System/: Geschäftslogik-Klasse.
  • Kernel/Modules/: Frontend-Controller.
  • Templates & Sprache: TT-Dateien + Übersetzungs-.pm.

3. Paket bauen & installieren

Abschnitt betitelt „3. Paket bauen & installieren“

3.1 OPM erzeugen

Abschnitt betitelt „3.1 OPM erzeugen“

Nutze das CLI-Tool, um aus deiner SOPM ein OPM zu bauen: MyExtension/

3.2 Installation

Abschnitt betitelt „3.2 Installation“

Admin-UI: Paket hochladen unter Admin → Einstellungen → Paketverwaltung. Konsole: Kernel/Config/Files/XML/MyExtension.xml Zum Deinstallieren bzw. Aktualisieren: Kernel/System/DynamicField/Driver/MyCustomField.pm

Abschnitt betitelt „Admin-UI: Paket hochladen unter Admin → Einstellungen → Paketverwaltung. Konsole: Kernel/Config/Files/XML/MyExtension.xml Zum Deinstallieren bzw. Aktualisieren: Kernel/System/DynamicField/Driver/MyCustomField.pm“

4. Erweiterungspunkte

Abschnitt betitelt „4. Erweiterungspunkte“

4.1 Dynamic Fields

Abschnitt betitelt „4.1 Dynamic Fields“

In Kernel/Config/Files/XML/MyExtension.xml registrierst du einen neuen Dynamic Field Driver: Kernel/System/Event/Handler/MyHandler.pm Implementiere den Driver in Kernel/System/DynamicField/Driver/MyCustomField.pm.

4.2 Event-Handler

Abschnitt betitelt „4.2 Event-Handler“

Melde deinen Event-Handler an: Run() Handler in Kernel/System/Event/Handler/MyHandler.pm implementieren (Run()-Methode).

4.3 Output-Filter

Abschnitt betitelt „4.3 Output-Filter“

Kernel/System/Output/Filter/MyFilter.pm Filter in Kernel/System/Output/Filter/MyFilter.pm.

Abschnitt betitelt „Kernel/System/Output/Filter/MyFilter.pm Filter in Kernel/System/Output/Filter/MyFilter.pm.“

5. Deployment & OTOpar

Abschnitt betitelt „5. Deployment & OTOpar“
  • Repository-Index: Erzeuge Packages.xml für eigenes Repo: Packages.xml
  • Füge unter SysConfig Package::RepositoryList deine Repo-URL ein.
  • OTOpar: Lade dein OPM bei https://otopar.perl-services.de hoch, damit andere es direkt installieren können.

6. Beispiel: MyCalendar-Paket

Abschnitt betitelt „6. Beispiel: MyCalendar-Paket“
  1. SOPM anlegen mit Name MyCalendar.
  2. DB-Skript sql/create_calendar.sql für Tabelle calendar_events.
  3. Konfig-XML definiert neues Ticket-Feld „Termin“.
  4. Core-Modul Kernel/System/CalendarEvent.pm mit CRUD-Methoden.
  5. Frontend-Module Kernel/Modules/AgentCalendar.pm, Template AgentCalendar.tt.
  6. Paket bauen und in OTOpar upladen.

7. Tipps & Best Practices

Abschnitt betitelt „7. Tipps & Best Practices“
  • Versionsnummer im sopm anpassen (SemVer).
  • DB-Migrationen in sql/ sauber versionieren.
  • Unit-Tests für System- und Module-Klassen anlegen.
  • Dokumentation im README plus POD in Perl-Modulen.
  • Translations in Language/de_*.pm und en_*.pm. Damit hast du eine solide Basis, um eigene Znuny-Plugins zu entwickeln, zu verteilen und in Kundenprojekten wartbar einzusetzen. Viel Spaß!

Individuelle Znuny Plugin- & Modulentwicklung

Benötigen Sie ein maßgeschneidertes Znuny-Paket oder müssen Altmodule aktualisiert werden? Softoft entwickelt release-sichere Erweiterungen.

Entwicklung anfragen

Häufig gestellte Fragen

Was ist eine SOPM-Datei und wofür wird sie in der Znuny-Plugin-Entwicklung benötigt?

Eine SOPM-Datei (Software Package Manager) ist eine XML-basierte Metadatendatei, die essenziell für jedes Znuny-Plugin ist. Sie enthält wichtige Informationen wie den eindeutigen Namen des Pakets, seine Version, die Kompatibilität mit bestimmten Znuny-Framework-Versionen und vor allem eine detaillierte Liste aller Dateien, die Teil des OPM-Pakets sind. Beim Installationsprozess liest Znuny diese Datei, um zu wissen, welche Dateien wohin kopiert werden müssen, welche Datenbankänderungen vorgenommen werden sollen oder welche Konfigurationen angewendet werden müssen. Ohne eine korrekt formatierte SOPM-Datei kann ein Plugin nicht als OPM-Paket erstellt oder installiert werden, da sie die Blaupause für das Deployment darstellt.

Quellen:

Wie strukturiert man ein Znuny-Plugin-Verzeichnis und welche Dateitypen sind wichtig?

Für ein Znuny-Plugin ist eine klare und standardisierte Verzeichnisstruktur entscheidend, typischerweise unter einem eigenen Verzeichnis wie MyExtension/. Innerhalb dieses Hauptverzeichnisses befinden sich die SOPM-Datei und weitere Unterverzeichnisse:

  • Kernel/Config/Files/XML/: Hier werden XML-Dateien abgelegt, die Module, Menüeinträge oder Dynamic Fields registrieren.
  • Kernel/System/: Enthält die Geschäftslogik-Klassen des Plugins.
  • Kernel/Modules/: Hier liegen die Frontend-Controller, die für die Darstellung im Agenten- oder Kundeninterface zuständig sind.
  • Templates/: Beherbergt die Template-Dateien (z.B. .tt für Template Toolkit) für die Benutzeroberfläche.
  • Language/: Enthält Dateien für die Internationalisierung, wie de_*.pm und en_*.pm für Übersetzungen.
  • sql/: Hier werden SQL-Skripte für Datenbankänderungen oder -erstellungen abgelegt.
    Diese Struktur gewährleistet eine einfache Wartung und Kompatibilität mit dem Znuny-Paketmanager.

Quellen:

Wie erstelle und installiere ich ein OPM-Paket für mein Znuny-Plugin?

Das Erstellen eines OPM-Pakets erfolgt über ein CLI-Tool, das die in der SOPM-Datei definierten Metadaten und die darin gelisteten Dateien zu einem einzigen .opm-Archiv zusammenführt. Der genaue Befehl hängt von der Znuny-Entwicklungsumgebung ab, aber im Kern wird die SOPM-Datei als Eingabe verwendet, um das Paket zu bauen. Nach der Erstellung gibt es zwei Hauptwege zur Installation:

  1. Über die Admin-UI: Melden Sie sich als Administrator bei Znuny an, navigieren Sie zu "Admin → Einstellungen → Paketverwaltung" und laden Sie Ihr .opm-Paket hoch. Das System führt dann die Installation durch.
  2. Über die Konsole: Für Entwickler und automatisierte Deployments kann das Paket auch über die Kommandozeile installiert werden. Dies ist besonders nützlich für Skripte oder wenn kein direkter Zugriff auf die Admin-UI besteht. Die genauen Befehle sind in der Znuny-Dokumentation zu finden und beinhalten oft das Ausführen eines Skripts mit dem Pfad zum OPM-Paket.

Zum Deinstallieren oder Aktualisieren eines Pakets werden ähnliche Wege beschritten, wobei der Paketmanager die Änderungen basierend auf der SOPM-Datei des neuen Pakets oder der Deinstallationsanweisungen verwaltet.

Quellen:

Welche Erweiterungspunkte bietet Znuny für die Plugin-Entwicklung und wie nutze ich sie?

Znuny bietet verschiedene Erweiterungspunkte, um die Kernfunktionalität anzupassen und zu erweitern:

  • Dynamic Fields: Ermöglichen das Hinzufügen benutzerdefinierter Felder zu Tickets, Kundenbenutzern oder anderen Objekten. Sie werden in einer Kernel/Config/Files/XML/MyExtension.xml registriert und der eigentliche Driver in Kernel/System/DynamicField/Driver/MyCustomField.pm implementiert.
  • Event-Handler: Diese reagieren auf bestimmte Ereignisse im System (z.B. Ticket-Erstellung, Artikel-Update). Sie werden ebenfalls in einer Konfigurations-XML-Datei angemeldet und die Logik in einer Run()-Methode in Kernel/System/Event/Handler/MyHandler.pm implementiert.
  • Output-Filter: Dienen dazu, den HTML-Output von Znuny zu manipulieren, bevor er an den Browser gesendet wird. Sie sind nützlich für das Hinzufügen von Tracking-Codes, das Ändern von Inhalten oder das Einfügen von JavaScript. Die Implementierung erfolgt in Kernel/System/Output/Filter/MyFilter.pm.
    Diese Erweiterungspunkte bieten eine flexible Möglichkeit, Znuny an spezifische Anforderungen anzupassen, ohne den Kerncode zu ändern.

Quellen:

Wie kann ich mein Znuny-Plugin bereitstellen und mit anderen teilen?

Nachdem Sie Ihr OPM-Paket erstellt haben, gibt es mehrere Wege, es bereitzustellen und zu teilen:

  • Eigenes Repository: Sie können ein eigenes Paket-Repository erstellen, indem Sie eine Packages.xml-Datei generieren, die Metadaten zu all Ihren OPM-Paketen enthält. Diese XML-Datei wird dann auf einem Webserver gehostet. Znuny-Instanzen können dieses Repository über die SysConfig-Einstellung Package::RepositoryList hinzufügen, um Ihre Plugins direkt über die Paketverwaltung zu finden und zu installieren.
  • OTOpar: Eine weitere beliebte Methode ist das Hochladen Ihres OPM-Pakets auf OTOpar. OTOpar ist eine zentrale Plattform, auf der Entwickler ihre OPM-Pakete öffentlich oder privat zur Verfügung stellen können. Dies ermöglicht anderen Znuny-Benutzern, Ihr Plugin einfach über die integrierte Paketverwaltung herunterzuladen und zu installieren, ähnlich wie bei einem App Store.
    Beide Methoden erleichtern die Verteilung und Aktualisierung Ihrer Plugins erheblich und fördern die Zusammenarbeit in der Znuny-Community.

Quellen:

Welche Best Practices sollte ich bei der Entwicklung von Znuny-Plugins beachten?

Für die Entwicklung robuster und wartbarer Znuny-Plugins sind einige Best Practices entscheidend:

  • Versionsnummerierung: Passen Sie die Versionsnummer in Ihrer SOPM-Datei sorgfältig an, idealerweise nach SemVer (Semantic Versioning), um Kompatibilität und Änderungen klar zu kommunizieren.
  • Datenbankmigrationen: Verwalten Sie Datenbankänderungen sauber in sql/-Skripten. Stellen Sie sicher, dass diese Skripte idempotent sind und Upgrades sowie Downgrades korrekt handhaben können.
  • Unit-Tests: Erstellen Sie Unit-Tests für Ihre Kernel/System/- und Kernel/Modules/-Klassen. Dies gewährleistet die Funktionalität und Stabilität Ihrer Codebasis bei Änderungen und Updates.
  • Dokumentation: Fügen Sie eine README-Datei zu Ihrem Plugin hinzu und verwenden Sie POD (Plain Old Documentation) in Ihren Perl-Modulen, um die Code-Funktionalität zu beschreiben. Eine gute Dokumentation ist für andere Entwickler und für die zukünftige Wartung unerlässlich.
  • Internationalisierung: Stellen Sie Übersetzungen in Language/de_*.pm und en_*.pm (und weiteren Sprachen) bereit, um Ihr Plugin für eine internationale Benutzerbasis zugänglich zu machen.
    Diese Praktiken tragen maßgeblich zur Qualität und Langlebigkeit Ihrer Znuny-Plugins bei.

Quellen: