Zum Inhalt springen
OTOBO Community Guide

Internes Erweitern des OTOBO-Kernsystems

In diesem Artikel lernst du, wie du OTOBO direkt im Kern anpasst – über XML-Konfiguration, Perl-Module und Templates. Wir zeigen dir Schritt für Schritt, wie du ein eigenes „HelloWorld“-Modul ins System einbindest.

1. Verzeichnisstruktur

Abschnitt betitelt „1. Verzeichnisstruktur“

Alle Anpassungen liegen unterhalb deines OTOBO-Clones im Kernel/-Verzeichnis:

Kernel/
├─ Config/Files/           # XML-Registrierungen
│  └─ XML/
├─ System/                 # Geschäftslogik-Module (Core)
├─ Modules/                # Frontend-Controller (Agent/Customer)
├─ Output/HTML/Standard/   # Template Toolkit (TT)-Templates
└─ Language/               # Übersetzungen

2. XML-Konfiguration

Abschnitt betitelt „2. XML-Konfiguration“

Neue Module und Routen werden per XML registriert. Lege in Kernel/Config/Files/XML/ eine Datei HelloWorld.xml an:

<?xml version="1.0" encoding="UTF-8"?>
<otobo_config version="2.0" init="Application">


  <!-- 1. Frontend-Modul registrieren -->
  <Setting Name="Frontend::Module###AgentHelloWorld" Required="1" Valid="1">
    <Navigation>Frontend::Agent::ModuleRegistration</Navigation>
    <Value>
      <Item ValueType="FrontendRegistration">
        <Hash>
          <Item Key="Group"><Array><Item>users</Item></Array></Item>
          <Item Key="Description" Translatable="1">HelloWorld Modul</Item>
          <Item Key="Title"       Translatable="1">HelloWorld</Item>
          <Item Key="NavBarName">HelloWorld</Item>
        </Hash>
      </Item>
    </Value>
  </Setting>


</otobo_config>

3. Core-Modul (Geschäftslogik)

Abschnitt betitelt „3. Core-Modul (Geschäftslogik)“

Erstelle in Kernel/System/HelloWorld.pm deine Logik:

package Kernel::System::HelloWorld;
use strict;
use warnings;
our @ObjectDependencies = ();


sub new {
    my ($Type, %Param) = @_;
    return bless {}, $Type;
}


sub GetHelloWorldText {
    my ($Self, %Param) = @_;
    return $Self->_FormatText(String => 'Hello World');
}


sub _FormatText {
    my ($Self, %Param) = @_;
    return uc $Param{String};
}


1;

4. Frontend-Modul (Controller)

Abschnitt betitelt „4. Frontend-Modul (Controller)“

In Kernel/Modules/AgentHelloWorld.pm bindest du deine Logik ins Agent-Frontend ein:

package Kernel::Modules::AgentHelloWorld;
use strict;
use warnings;


sub new { bless {}, shift }


sub Run {
    my ($Self, %Param) = @_;


    my $HelloObj    = $Kernel::OM->Get('Kernel::System::HelloWorld');
    my $LayoutObj   = $Kernel::OM->Get('Kernel::Output::HTML::Layout');
    my %Data;


    $Data{Text} = $HelloObj->GetHelloWorldText();


    return
        $LayoutObj->Header(Title => 'HelloWorld')
      . $LayoutObj->NavigationBar()
      . $LayoutObj->Output(
          TemplateFile => 'AgentHelloWorld',
          Data         => \%Data,
        )
      . $LayoutObj->Footer();
}


1;

5. Templates (TT)

Abschnitt betitelt „5. Templates (TT)“

Lege in Kernel/Output/HTML/Standard/AgentHelloWorld.tt folgendes Template an:

[% Data.Text %]


<p>Das ist dein selbst erstelltes HelloWorld-Modul!</p>

6. Beispiel-Workflow

Abschnitt betitelt „6. Beispiel-Workflow“

  1. Neu laden:

    Terminal-Fenster
    bin/otobo.Console.pl Maint::Config::Rebuild

  2. Cache leeren:

    Terminal-Fenster
    bin/otobo.Console.pl Maint::Cache::Delete

  3. Browser öffnen: Agent-Interface → Menü → „HelloWorld“

7. Tipps & Best Practices

Abschnitt betitelt „7. Tipps & Best Practices“
  • ObjectDependencies sauber deklarieren (z.B. DB, Layout).
  • POD-Dokumentation in Perl-Modulen nicht vergessen.
  • Übersetzungen unter Kernel/Language/de_*.pm pflegen.
  • Unit-Tests mit Mojolicious einrichten (optional).
  • Nach jeder Änderung Config rebuild & Cache löschen.

Damit hast du eine solide Vorlage, um weitere Kern-Erweiterungen in OTOBO zu realisieren. Viel Spaß beim Entwickeln!

Individuelle OTOBO Modul- & Plugin-Entwicklung

Benötigen Sie maßgeschneiderte Funktionen oder Paket-Upgrades? Softoft entwickelt release-sichere Perl- & Frontend-Erweiterungen.

Entwicklung besprechen

Häufig gestellte Fragen

Wo genau im OTOBO-Kernsystem werden Anpassungen vorgenommen und welche Rolle spielen die einzelnen Verzeichnisse dabei?

Anpassungen am OTOBO-Kernsystem werden primär im Kernel/-Verzeichnis vorgenommen, das die gesamte Geschäftslogik und Konfiguration beherbergt. Jedes Unterverzeichnis hat eine spezifische Funktion:

  • Kernel/Config/Files/XML/ ist der Ort, an dem neue Module, Routen und Systemeinstellungen über XML-Dateien registriert werden. Hier definierst du, wie OTOBO deine Erweiterungen erkennt und integriert.
  • Kernel/System/ enthält die Core-Perl-Module, die die eigentliche Geschäftslogik und Datenverarbeitung implementieren. Dies sind die "Backend"-Komponenten deiner Erweiterung.
  • Kernel/Modules/ beherbergt die Frontend-Controller, die die Interaktion mit der Benutzeroberfläche (Agenten- oder Kunden-Interface) steuern. Sie rufen die Geschäftslogik aus Kernel/System/ auf und bereiten Daten für die Darstellung vor.
  • Kernel/Output/HTML/Standard/ ist für die Template-Toolkit-Templates zuständig, die die visuelle Ausgabe im Browser generieren. Hier wird festgelegt, wie die vom Frontend-Modul bereitgestellten Daten dem Benutzer präsentiert werden.
  • Kernel/Language/ dient der Verwaltung von Übersetzungen für alle Texte, die in deinen Modulen und Templates verwendet werden.
    Diese Struktur ermöglicht eine klare Trennung von Konfiguration, Logik, Präsentation und Internationalisierung, was die Wartbarkeit und Erweiterbarkeit des Systems fördert.

Quellen

Wie werden neue Frontend-Module in OTOBO registriert und welche XML-Konfiguration ist dafür notwendig?

Neue Frontend-Module in OTOBO werden über XML-Konfigurationsdateien registriert, die im Verzeichnis Kernel/Config/Files/XML/ abgelegt werden. Diese XML-Dateien definieren die Metadaten und Eigenschaften des Moduls, sodass OTOBO es im System erkennen und korrekt routen kann. Ein typisches Beispiel ist die Registrierung eines "HelloWorld"-Moduls, wie in der Dokumentation beschrieben. Hierfür wird eine Datei wie HelloWorld.xml erstellt, die eine <Setting>-Definition enthält.
Innerhalb dieser <Setting> wird der Name des Moduls (z.B. Frontend::Module###AgentHelloWorld) sowie wichtige Navigationsinformationen und Beschreibungen festgelegt. Dazu gehören die Group, die die Sichtbarkeit des Moduls für bestimmte Benutzergruppen steuert, eine Description und ein Title (beide Translatable="1" für Mehrsprachigkeit) und ein NavBarName, der festlegt, wie das Modul im Navigationsmenü erscheint. Diese XML-Konfiguration ist entscheidend, da sie OTOBO mitteilt, dass ein neues Modul existiert und wie es in die Benutzeroberfläche integriert werden soll. Ohne diese Registrierung würde OTOBO das Modul nicht finden und nicht korrekt aufrufen können.

Quellen

Welche Schritte sind erforderlich, um ein eigenes Core-Perl-Modul für die Geschäftslogik in OTOBO zu erstellen?

Um ein eigenes Core-Perl-Modul für die Geschäftslogik in OTOBO zu erstellen, legst du eine neue .pm-Datei im Verzeichnis Kernel/System/ an, beispielsweise Kernel/System/HelloWorld.pm. Jedes Perl-Modul beginnt mit der Deklaration des Pakets (package Kernel::System::HelloWorld;) und der Aktivierung von strict und warnings für eine saubere Code-Entwicklung.
Das Modul benötigt eine new-Methode, die als Konstruktor fungiert und eine Instanz des Moduls zurückgibt. In dieser Methode können Initialisierungen vorgenommen werden, obwohl sie im einfachen "HelloWorld"-Beispiel leer bleibt. Die eigentliche Geschäftslogik wird in weiteren Subroutinen implementiert. Zum Beispiel könnte eine Methode GetHelloWorldText definiert werden, die den gewünschten Text generiert. Es ist auch gängige Praxis, Hilfsmethoden (oft mit einem Unterstrich beginnend, z.B. _FormatText) zu erstellen, um Code zu strukturieren und wiederverwendbar zu machen. Diese Methoden können dann von anderen Modulen aufgerufen werden, um spezifische Aufgaben zu erledigen, wie das Formatieren von Strings oder das Abrufen von Daten. Wichtig ist, dass das Modul am Ende mit 1; abgeschlossen wird, um anzuzeigen, dass es erfolgreich geladen wurde.

Quellen

Wie bindet man die Geschäftslogik eines Core-Moduls in das OTOBO-Frontend ein und welche Aufgaben hat ein Frontend-Modul dabei?

Die Einbindung der Geschäftslogik eines Core-Moduls in das OTOBO-Frontend erfolgt über ein Frontend-Modul, das im Verzeichnis Kernel/Modules/ erstellt wird, zum Beispiel Kernel/Modules/AgentHelloWorld.pm. Dieses Modul fungiert als Controller, der die Anfragen des Benutzers verarbeitet und die entsprechenden Aktionen ausführt.
Ein Frontend-Modul benötigt ebenfalls eine new-Methode und vor allem eine Run-Methode. Die Run-Methode ist der zentrale Einstiegspunkt, wenn das Modul über die URL aufgerufen wird. In dieser Methode werden folgende Schritte ausgeführt:

  • Objekte abrufen: Mithilfe von $Kernel::OM->Get() werden Instanzen anderer benötigter OTOBO-Objekte abgerufen, wie das zuvor erstellte Core-Modul (Kernel::System::HelloWorld) und das Layout-Objekt (Kernel::Output::HTML::Layout).
  • Daten vorbereiten: Die Geschäftslogik des Core-Moduls wird aufgerufen, um die für die Anzeige benötigten Daten zu ermitteln (z.B. $HelloObj->GetHelloWorldText()). Diese Daten werden in einem Hash (%Data) gesammelt.
  • Ausgabe generieren: Das Layout-Objekt wird verwendet, um die HTML-Struktur der Seite zu erstellen. Dies umfasst den Header mit dem Seitentitel, die NavigationBar und den Footer. Der wichtigste Teil ist der Aufruf von $LayoutObj->Output(), der das entsprechende Template-Toolkit-Template (TemplateFile => 'AgentHelloWorld') lädt und die vorbereiteten Daten (Data => \%Data) an dieses Template übergibt.
    Das Frontend-Modul orchestriert somit den gesamten Prozess von der Datenbeschaffung bis zur finalen HTML-Ausgabe für den Browser.

Quellen

Wie werden Template-Toolkit-Templates in OTOBO erstellt und mit Daten aus dem Frontend-Modul befüllt?

Template-Toolkit-Templates (TT-Templates) in OTOBO werden erstellt, indem man eine .tt-Datei im Verzeichnis Kernel/Output/HTML/Standard/ ablegt, zum Beispiel Kernel/Output/HTML/Standard/AgentHelloWorld.tt. Diese Templates sind für die visuelle Darstellung der Daten im Browser zuständig und werden vom Frontend-Modul mit den benötigten Informationen befüllt.
Die Syntax von Template Toolkit ermöglicht es, dynamische Inhalte einfach in statisches HTML einzubetten. Daten, die vom Frontend-Modul über den Data-Hash übergeben werden, können im Template direkt über die Punktnotation angesprochen werden. Wenn das Frontend-Modul beispielsweise einen Hash %Data mit dem Schlüssel Text übergibt (z.B. $Data{Text} = 'Hello World';), kann dieser Wert im Template mit [% Data.Text %] ausgegeben werden.
Zusätzlich zu den dynamischen Platzhaltern können Templates auch statischen HTML-Inhalt oder andere Template-Toolkit-Direktiven enthalten, um die Struktur und das Design der Seite zu gestalten. Im "HelloWorld"-Beispiel wird neben dem dynamischen Text auch ein einfacher Absatz Das ist dein selbst erstelltes HelloWorld-Modul! hinzugefügt. Die Trennung von Logik (Perl-Module) und Präsentation (Templates) ist ein Kernprinzip von OTOBO und erleichtert die Entwicklung und Wartung von Erweiterungen erheblich.

Quellen

Welche Schritte sind nach der Entwicklung eines neuen Moduls notwendig, um es in OTOBO sichtbar und funktionsfähig zu machen?

Nachdem ein neues Modul in OTOBO entwickelt wurde – bestehend aus XML-Konfiguration, Core-Modul, Frontend-Modul und Template –, sind einige entscheidende Schritte notwendig, um es im System sichtbar und funktionsfähig zu machen. Diese Schritte stellen sicher, dass OTOBO die neuen Dateien erkennt und in seine interne Konfiguration integriert.
Zuerst muss die OTOBO-Konfiguration neu aufgebaut werden. Dies geschieht über den Konsolenbefehl bin/otobo.Console.pl Maint::Config::Rebuild. Dieser Befehl scannt alle Konfigurationsdateien, einschließlich deiner neuen XML-Datei, und aktualisiert die interne Systemkonfiguration. Ohne diesen Schritt würde OTOBO die Registrierung deines neuen Moduls nicht erkennen.
Anschließend ist es unerlässlich, den OTOBO-Cache zu leeren. Dies wird mit dem Befehl bin/otobo.Console.pl Maint::Cache::Delete durchgeführt. OTOBO verwendet umfangreiche Caching-Mechanismen, um die Performance zu verbessern. Wenn der Cache nicht geleert wird, könnte das System weiterhin alte oder nicht aktualisierte Informationen verwenden, was dazu führen würde, dass dein neues Modul nicht korrekt angezeigt oder ausgeführt wird.
Nachdem diese beiden Befehle erfolgreich ausgeführt wurden, kannst du das Agenten-Interface in deinem Browser öffnen. Dein neues Modul sollte nun im Navigationsmenü erscheinen, beispielsweise unter dem Namen "HelloWorld", wie in der XML-Konfiguration definiert. Ein Klick darauf sollte die von dir erstellte Seite mit dem "Hello World"-Text anzeigen. Diese Schritte sind nach jeder Änderung an der Kernkonfiguration oder an Modulen notwendig, um die Änderungen im laufenden System zu aktivieren.

Quellen

Welche Best Practices und wichtigen Tipps sollten bei der Entwicklung von OTOBO-Kern-Erweiterungen beachtet werden?

Bei der Entwicklung von OTOBO-Kern-Erweiterungen gibt es mehrere Best Practices und wichtige Tipps, die eine reibungslose Entwicklung und eine gute Wartbarkeit sicherstellen.

  1. ObjectDependencies sauber deklarieren: In deinen Perl-Modulen solltest du alle benötigten OTOBO-Objekte (wie Kernel::System::DB oder Kernel::Output::HTML::Layout) explizit in @ObjectDependencies deklarieren. Dies verbessert die Lesbarkeit, erleichtert das Testen und hilft OTOBO, Abhängigkeiten korrekt zu verwalten.
  2. POD-Dokumentation verwenden: Füge in deinen Perl-Modulen aussagekräftige POD-Dokumentation (Plain Old Documentation) hinzu. Dies erklärt die Funktion des Moduls, seiner Methoden, Parameter und Rückgabewerte. Es ist entscheidend für die langfristige Verständlichkeit und Wartbarkeit deines Codes, besonders in größeren Projekten oder Teams.
  3. Übersetzungen pflegen: Wenn dein Modul Texte für die Benutzeroberfläche enthält, sorge dafür, dass diese übersetzbar sind. Lege entsprechende Einträge in den Sprachdateien unter Kernel/Language/de_*.pm (oder anderen Sprachen) an und verwende die OTOBO-Mechanismen für die Textübersetzung in deinen Templates und Modulen.
  4. Unit-Tests einrichten (optional, aber empfohlen): Für komplexere Module ist es ratsam, Unit-Tests zu schreiben. OTOBO basiert auf Perl, und Test-Frameworks wie Mojolicious können hierbei helfen, die Funktionalität deiner Erweiterungen automatisiert zu überprüfen und Regressionen zu vermeiden.
  5. Config rebuild und Cache löschen nach jeder Änderung: Wie im Workflow beschrieben, sind die Befehle bin/otobo.Console.pl Maint::Config::Rebuild und bin/otobo.Console.pl Maint::Cache::Delete nach jeder Änderung an Konfiguration oder Code im Kernel/-Verzeichnis unerlässlich, um sicherzustellen, dass OTOBO die neuesten Versionen deiner Dateien verwendet.
    Die Beachtung dieser Punkte trägt maßgeblich zur Qualität und Stabilität deiner OTOBO-Erweiterungen bei.

Quellen