OTOBO REST API erweitern: eigene Generic-Interface-Operationen

In diesem Guide: Das OTOBO Generic Interface um sichere REST-Operationen erweitern – anhand der Katalog-Endpunkte des OpenTicketAIConnector als praxiserprobtem Paketmuster.

Verwandte Themen: OTOBO REST API · Web Services · Plugin-Entwicklung

Die Standardoperationen der OTOBO REST API wie TicketCreate, TicketGet und TicketSearch decken viele Integrationen ab. Für Queue-Metadaten, Dynamic-Field-Werte, Konfigurationsdaten oder fachspezifische Aktionen benötigen Sie jedoch oft eigene Endpoints. Diese gehören in eine paketierte OTOBO-Generic-Interface-Erweiterung – nicht allein in ein YAML-Mapping.

Benötigen Sie eine eigene OTOBO-REST-Operation?

Softoft entwickelt Generic-Interface-Operationen, sichere Webservices, OTOBO-Pakete, Tests, Deployment und Übergabedokumentation.

API-Erweiterung besprechen

Buchen Sie ein 15-minütiges Erstgespräch, wenn bereits feststeht, welche Daten oder Aktionen der Endpoint bereitstellen soll.

Architektur

Eine eigene REST-Schnittstelle besteht aus vier verbundenen Ebenen:

Ebene	Was Sie ergänzen	Ausführung
Operation	`Kernel/GenericInterface/Operation/<Controller>/<Name>.pm`	Bei jedem Request
Registrierung	`GenericInterface::Operation::Module###…` in SysConfig-XML	Beim Konfigurationsaufbau
Webservice	Provider-Operation und `RouteOperationMapping` in YAML	Beim REST-Routing
Paket	`.sopm`-Dateiliste und Install-/Upgrade-Hooks	Im Paket-Lebenszyklus

flowchart LR
  client[HTTPClient] --> gi["Generic Interface HTTP REST"]
  gi --> route[WebserviceRoute]
  route --> operation[PerlOperation]
  operation --> core["OTOBO Kernel System APIs"]
  operation --> response[JSONResponse]

Fehlt eine Ebene, erscheint die Operation nicht unter Admin → Web Services, die Route liefert 404 oder die Erweiterung fehlt nach der nächsten Paketinstallation.

Die Beispiele verwenden TicketAICatalog::QueueList, ein reales Muster aus OpenTicketAIConnector. Ersetzen Sie Controller, Operationsname, API-Benutzer und Webservice-Namen durch Werte Ihres eigenen Pakets.

Schritt 1 – Perl-Operation entwickeln

Benennung und Basisklasse

Package: Kernel::GenericInterface::Operation::<Controller>::<Name>
Datei: Kernel/GenericInterface/Operation/<Controller>/<Name>.pm
Generic-Interface-Typ: <Controller>::<Name>

Operationen erben von Kernel::GenericInterface::Operation::Common. Die Klasse stellt Auth und ReturnError bereit. Eine gemeinsame Basisklasse lohnt sich, sobald mehrere Operationen dieselben Prüfungen benötigen.

package Kernel::GenericInterface::Operation::TicketAICatalog::Base;

use strict;
use warnings;
use parent qw(Kernel::GenericInterface::Operation::Common);

our $ObjectManagerDisabled = 1;

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

    for my $Needed (qw(DebuggerObject WebserviceID)) {
        return if !$Param{$Needed};
        $Self->{$Needed} = $Param{$Needed};
    }
    return $Self;
}

sub _AuthOrError {
    my ( $Self, %Param ) = @_;
    my ( $UserID, $UserType ) = $Self->Auth(%Param);
    return ( $UserID, undef ) if $UserID;

    return (
        undef,
        $Self->ReturnError(
            ErrorCode    => 'TicketAICatalog.AuthFail',
            ErrorMessage => 'Authentication failed!',
        ),
    );
}

1;

$ObjectManagerDisabled = 1 ist erforderlich, weil Generic-Interface-Operationen außerhalb des normalen Object-Manager-Factory-Pfads erzeugt werden.

`Run` implementieren

Greifen Sie über $Kernel::OM auf OTOBO-Kernel-APIs zu und definieren Sie Validierung und Response-Formate eindeutig.

package Kernel::GenericInterface::Operation::TicketAICatalog::QueueList;

use strict;
use warnings;
use parent qw(Kernel::GenericInterface::Operation::TicketAICatalog::Base);

our $ObjectManagerDisabled = 1;

sub Run {
    my ( $Self, %Param ) = @_;
    my ( $UserID, $Error ) = $Self->_AuthOrError(%Param);
    return $Error if $Error;

    my $QueueObject = $Kernel::OM->Get('Kernel::System::Queue');
    my %Queues = $QueueObject->QueueList( Valid => 0 );
    my @Items;

    for my $QueueID ( sort { $a <=> $b } keys %Queues ) {
        my %Queue = $QueueObject->QueueGet( ID => $QueueID );
        next if !%Queue;
        push @Items, {
            ID      => $QueueID + 0,
            Name    => $Queue{Name} // $Queues{$QueueID},
            Comment => $Queue{Comment} // '',
            Valid   => ( ( $Queue{ValidID} // 1 ) == 1 ) ? 1 : 0,
        };
    }

    return { Success => 1, Data => { Item => \@Items } };
}

1;

Dekodierte JSON- oder Query-Parameter stehen in $Param{Data}. Anmeldedaten bleiben Geschwisterschlüssel, die Auth verarbeitet.

my $Data = $Param{Data} || {};
my $Name = $Data->{Name} // '';

return $Self->ReturnError(
    ErrorCode    => 'TicketAICatalog.MissingName',
    ErrorMessage => 'Name is required.',
) if !$Name;

Bevorzugen Sie idempotente, lesende Operationen. Schreibende Aktionen erhalten eigene Routen, vollständige Validierung und einen dedizierten API-Benutzer.

Schritt 2 – Operation in SysConfig registrieren

OTOBO erkennt Operationsmodule über Einstellungen mit diesem Namen:

GenericInterface::Operation::Module###<Controller>::<Name>

Registrieren Sie jeden Typ in einer XML-Datei unter Kernel/Config/Files/XML/:

<?xml version="1.0" encoding="utf-8"?>
<otobo_config version="2.0" init="Application">
    <Setting Name="GenericInterface::Operation::Module###TicketAICatalog::QueueList"
             Required="0" Valid="1">
        <Description Translatable="1">Catalogue: list queues.</Description>
        <Navigation>GenericInterface::Operation::ModuleRegistration</Navigation>
        <Value>
            <Hash>
                <Item Key="Name">QueueList</Item>
                <Item Key="Controller">TicketAICatalog</Item>
                <Item Key="ConfigDialog">AdminGenericInterfaceOperationDefault</Item>
            </Hash>
        </Value>
    </Setting>
</otobo_config>

Nach Paketinstallation und Konfigurationsaufbau muss TicketAICatalog::QueueList in der Webservice-Administration als Operationstyp auswählbar sein.

Schritt 3 – REST-Route im Webservice zuordnen

Die Registrierung macht das Backend auswählbar. Das Webservice-YAML stellt es über HTTP bereit:

Provider:
  Operation:
    queue-list:
      Type: TicketAICatalog::QueueList
      Description: Lists queues with ID, name, comment, and validity.
      MappingInbound:
        Type: Simple
        Config:
          KeyMapDefault:
            MapTo: ""
            MapType: Keep
          ValueMap:
            UserLogin:
              ValueMapRegEx:
                .*: custom-api-user
      MappingOutbound:
        Type: Simple
        Config:
          KeyMapDefault:
            MapTo: ""
            MapType: Keep

Transport:
  Type: HTTP::REST
  Config:
    MaxLength: "1000000"
    RouteOperationMapping:
      queue-list:
        Route: /queue-list
        RequestMethod:
          - GET
          - POST

Der Schlüssel unter Provider.Operation muss exakt dem Schlüssel unter RouteOperationMapping entsprechen. Ein Inbound-Login-Rewrite kann alle Requests auf einen eingeschränkten API-Agenten zwingen, ersetzt aber weder HTTPS noch starkes Passwort, Gruppenrechte, Eingabevalidierung und Netzwerkkontrollen.

Schritt 4 – Erweiterung paketieren und installieren

Jede Perl-, XML- und YAML-Datei muss in der .sopm stehen. Andernfalls landet sie nicht auf dem Zielsystem.

<Filelist>
    <File Permission="644"
          Location="Kernel/GenericInterface/Operation/TicketAICatalog/Base.pm"/>
    <File Permission="644"
          Location="Kernel/GenericInterface/Operation/TicketAICatalog/QueueList.pm"/>
    <File Permission="644"
          Location="Kernel/Config/Files/XML/MyConnector.xml"/>
    <File Permission="644"
          Location="var/webservices/examples/MyConnector.yml"/>
</Filelist>

Paket-Hooks erstellen den eingeschränkten API-Benutzer und importieren beziehungsweise aktualisieren das YAML:

<CodeInstall Type="post"><![CDATA[
    $Kernel::OM->Get('Kernel::System::MyConnector::Setup')->Install();
]]></CodeInstall>
<CodeReinstall Type="post"><![CDATA[
    $Kernel::OM->Get('Kernel::System::MyConnector::Setup')->Install();
]]></CodeReinstall>
<CodeUpgrade Type="post"><![CDATA[
    $Kernel::OM->Get('Kernel::System::MyConnector::Setup')->Install();
]]></CodeUpgrade>
<CodeUninstall Type="pre"><![CDATA[
    $Kernel::OM->Get('Kernel::System::MyConnector::Setup')->Uninstall();
]]></CodeUninstall>

Aktualisieren Sie den Datenbank-Webservice bei Upgrades immer aus dem paketierten YAML. So gelangen neue Routen ohne manuelle Admin-Schritte ins System.

Schritt 5 – Endpoint testen

Die URL folgt diesem Muster:

https://helpdesk.example/otobo/nph-genericinterface.pl/Webservice/MyConnector/queue-list

Ein Smoke-Test prüft Authentifizierung, Methode, Route und JSON:

curl -sS -u 'custom-api-user:API_PASSWORD' \
  -X POST \
  'https://helpdesk.example/otobo/nph-genericinterface.pl/Webservice/MyConnector/queue-list'

Testen Sie Erfolg und stabile Fehler, unberechtigten Zugriff, ungültige Eingaben, leere Ergebnisse, große Responses und Paket-Upgrades. Client-Code sollte dokumentierte Response-Verträge verwenden statt interne Perl-Klassen zu kennen.

Checkliste

Operations-.pm mit new, Run, Authentifizierung, Validierung und stabilem Data-Format ergänzen.
GenericInterface::Operation::Module###<Controller>::<Name> in SysConfig-XML registrieren.
Provider-Operation und REST-Route ins paketierte YAML aufnehmen.
Alle Dateien in die .sopm eintragen und Paketversion erhöhen.
Webservice in Install- und Upgrade-Hooks importieren oder aktualisieren.
Dem API-Benutzer nur benötigte Gruppen und Queues zuweisen.
Unit-, Integrations-, Berechtigungs- und Upgrade-Tests ergänzen.
Operation unter Admin → Web Services prüfen und über HTTPS testen.

Fehlerbehebung

Operation fehlt im Admin: XML-Einstellungsname, Controller, Operationsname, Paket-Dateiliste und Konfigurationsaufbau prüfen.
HTTP 404: YAML wurde nicht importiert oder der Operationsschlüssel stimmt nicht mit RouteOperationMapping überein.
Authentifizierung fehlgeschlagen: Credentials passen nicht zum per Inbound-Mapping erzwungenen Benutzer oder dessen Rechte fehlen.
Leeres Item: Valid-Filter sowie Gruppen- und Queue-Rechte des API-Benutzers prüfen.
Unerwartete Response: Gemappte Request- und Response-Daten im Generic-Interface-Debugger untersuchen.
Route fehlt nach Upgrade: Upgrade-Hook muss das vollständige paketierte YAML per WebserviceUpdate erneut importieren.

Individuelle OTOBO-API-Erweiterung beauftragen

Eigene Operationen sind Produktivcode innerhalb Ihres Ticketsystems. Sie benötigen sichere Autorisierung, stabile Verträge, Paket-Lifecycle, Tests und eine Upgrade-Strategie – nicht nur ein funktionierendes Perl-Modul.

Softoft entwickelt und wartet Ihre OTOBO-REST-Erweiterung

Von Anforderung und Operationsdesign über Paketlieferung und Deployment bis zu Dokumentation und Wartung.

API-Programmierung anfragen

Buchen Sie ein 15-minütiges Gespräch, um Endpoints, angebundenes System und Deployment-Umgebung zu besprechen.

Häufig gestellte Fragen

Kann man die OTOBO REST API um eigene Endpoints erweitern?

Ja. Dazu entwickeln Sie eine Generic-Interface-Operation, registrieren sie in SysConfig, ordnen ihr eine REST-Route zu und liefern alle Dateien als OTOBO-Paket aus.

Warum erscheint eine eigene Operation nicht unter Admin → Web Services?

Meist fehlt die GenericInterface::Operation::Module-Registrierung in SysConfig oder Paket und Konfiguration wurden nach der Installation nicht neu aufgebaut.

Kann Softoft eine individuelle OTOBO-REST-API-Erweiterung entwickeln?

Ja. Softoft entwickelt Generic-Interface-Operationen, Webservices, OTOBO-Pakete, Tests, Deployment und Wartung.