Zum Inhalt springen
Znuny Logo Znuny Community Docs

Znuny REST API erweitern: eigene Generic-Interface-Operationen

In diesem Guide: Sichere eigene REST-Operationen zum Znuny Generic Interface hinzufügen – mit den Katalogoperationen des OpenTicketAIConnector als realem Paketbeispiel.

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

Das Znuny Generic Interface enthält Standardoperationen für Tickets. Integrationen benötigen jedoch häufig zusätzliche Daten oder Aktionen: Queue-Details, Auswahlwerte von Dynamic Fields, Konfigurationskataloge oder anwendungsspezifische Befehle. Eine wartbare Znuny-REST-API-Erweiterung verbindet Perl-Code, SysConfig-Registrierung, REST-Routing, Paket-Lifecycle und Berechtigungen.

Benötigen Sie einen eigenen Znuny-REST-Endpoint?

Softoft entwickelt sichere Generic-Interface-Operationen, Znuny-Pakete, automatisierte Tests, Deployment und wartbare API-Verträge.

Znuny API besprechen

Buchen Sie ein 15-minütiges Erstgespräch, um angebundenes System und benötigte Operationen zu besprechen.

Aufbau einer eigenen Znuny-Operation

Abschnitt betitelt „Aufbau einer eigenen Znuny-Operation“
flowchart LR
  client[IntegrationClient] --> transport["Generic Interface REST Transport"]
  transport --> mapping[WebserviceRoute]
  mapping --> operation[CustomPerlOperation]
  operation --> znunyCore["Znuny Kernel System APIs"]
  operation --> json[StableJSONContract]

Vier Bestandteile müssen zusammenpassen:

  1. Perl-Operation – verarbeitet gemappte Request-Daten, authentifiziert, ruft Znuny-Kernel-APIs auf und liefert ein stabiles Ergebnis.
  2. SysConfig-XML – registriert Controller und Operation für die Admin-Oberfläche.
  3. Webservice-YAML – verbindet den Operationstyp mit REST-Pfad und HTTP-Methoden.
  4. Znuny-Paket – installiert alle Dateien und importiert oder aktualisiert die Webservice-Konfiguration.

Die Beispiele verwenden den Controller TicketAICatalog aus OpenTicketAIConnector. Er stellt Katalogdaten bereit, die Standard-Ticketoperationen nicht ausreichend abdecken. Das eigene Paket sollte einen eigenen Controller- und Webservice-Namen verwenden.

Schritt 1 – Operations-Backend entwickeln

Abschnitt betitelt „Schritt 1 – Operations-Backend entwickeln“

Klassen- und Dateinamen

Abschnitt betitelt „Klassen- und Dateinamen“
Klasse: Kernel::GenericInterface::Operation::<Controller>::<Name>
Datei:  Kernel/GenericInterface/Operation/<Controller>/<Name>.pm
Typ:    <Controller>::<Name>

Generic-Interface-Operationen erben von Kernel::GenericInterface::Operation::Common. Die Klasse stellt Authentifizierung und strukturierte Fehler bereit.

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 für diese Operationsklassen erforderlich. Eine gemeinsame Basisklasse sollte nur tatsächlich geteiltes Verhalten enthalten.

Znuny-Daten in Run lesen

Abschnitt betitelt „Znuny-Daten in Run lesen“
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;

Gemappte Request-Felder stehen in $Param{Data}. Prüfen Sie Pflichtfelder vor dem Kernel-Aufruf und liefern Sie stabile Fehlercodes mit ReturnError.

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


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

Lesende Katalogoperationen sind am sichersten. Schreibende Operationen benötigen Typ- und Werteprüfung, möglichst idempotentes Verhalten und eigene explizite Routen.

Schritt 2 – Modul in Znuny SysConfig registrieren

Abschnitt betitelt „Schritt 2 – Modul in Znuny SysConfig registrieren“

Znuny sucht nach Einstellungen dieses Musters:

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

Verwenden Sie die Znuny-/OTRS-kompatible Wurzel <otrs_config>:

<?xml version="1.0" encoding="utf-8"?>
<otrs_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>
</otrs_config>

Nach Paketinstallation und Konfigurationsaufbau muss TicketAICatalog::QueueList unter Admin → Web Services auswählbar sein.

Schritt 3 – REST-Provider konfigurieren

Abschnitt betitelt „Schritt 3 – REST-Provider konfigurieren“

Definieren Sie Operation und Route im paketierten Webservice-YAML:

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

Die Schlüssel queue-list müssen übereinstimmen. Verwenden Sie einen dedizierten API-Agenten mit minimalen Gruppen- und Queue-Rechten. Der Login-Rewrite ergänzt HTTPS, starke Zugangsdaten, Netzwerkkontrollen und Eingabevalidierung – er ersetzt sie nicht.

Schritt 4 – Znuny-Paket-Lifecycle erstellen

Abschnitt betitelt „Schritt 4 – Znuny-Paket-Lifecycle erstellen“

Znuny-Paketmanifeste verwenden <otrs_package>. Deklarieren Sie nur Framework-Versionen, die mit den unterstützten Znuny-Releases getestet wurden. Jede Backend-, XML-, YAML- und Setup-Datei gehört in die Dateiliste:

<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/MyZnunyConnector.xml"/>
    <File Permission="644"
          Location="var/webservices/MyZnunyConnector.yml"/>
</Filelist>

Install-, Reinstall- und Upgrade-Hooks rufen ein Znuny-spezifisches Setup-Modul auf:

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

Das Setup-Modul erstellt oder aktualisiert den eingeschränkten API-Benutzer und importiert das YAML über Kernel::System::GenericInterface::Webservice. Bei Paket-Upgrades muss es den bestehenden Webservice aktualisieren statt einen zweiten anzulegen.

Schritt 5 – Route aufrufen und testen

Abschnitt betitelt „Schritt 5 – Route aufrufen und testen“

Der Installationspfad kann /znuny/ oder /otrs/ lauten. Verwenden Sie den Pfad Ihrer Umgebung:

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

Testen Sie das Paket auf jeder angegebenen Znuny-Framework-Version: erfolgreiche Responses, Authentifizierungsfehler, fehlende Queue-Rechte, ungültige Eingaben, leere Daten, Response-Größe, Reinstall, Upgrade und Uninstall.

Znuny-Checkliste

Abschnitt betitelt „Znuny-Checkliste“
  1. Operationsmodul mit Authentifizierung, Validierung und stabilem Data-Vertrag erstellen.
  2. Typ in einer <otrs_config>-SysConfig-XML-Datei registrieren.
  3. Übereinstimmende Provider-Operations- und Routenschlüssel ins Webservice-YAML aufnehmen.
  4. Alle Dateien ins <otrs_package>-Manifest eintragen und getestete Framework-Versionen deklarieren.
  5. Webservice bei Paketinstallation und Upgrade importieren oder aktualisieren.
  6. API-Benutzer auf erforderliche Gruppen, Queues und Aktionen beschränken.
  7. Paket und Operation auf jeder unterstützten Znuny-Version testen.
  8. Operation unter Admin → Web Services prüfen und über HTTPS testen.

Fehlerbehebung

Abschnitt betitelt „Fehlerbehebung“
  • Operation fehlt: SysConfig-XML, Controller, Name, Paket-Dateiliste und Konfigurationsaufbau prüfen.
  • Route liefert 404: YAML wurde nicht importiert oder Route und Operationsschlüssel unterscheiden sich.
  • Authentifizierung schlägt fehl: Basic-Auth-Zugangsdaten passen nicht zum gemappten API-Benutzer.
  • Operation liefert keine Daten: Valid-Flags sowie Gruppen- und Queue-Rechte prüfen.
  • Paket läuft nur auf einem Release: Framework-Tags und Kompatibilität der Kernel-APIs prüfen.
  • Neue Routen fehlen nach Upgrade: Setup muss das vollständige YAML laden und WebserviceUpdate aufrufen.

Znuny-REST-API-Erweiterung beauftragen

Abschnitt betitelt „Znuny-REST-API-Erweiterung beauftragen“

Eine dauerhafte Erweiterung braucht mehr als einen Perl-Prototyp: Vertragsdesign, Least-Privilege-Zugriff, Paketkompatibilität, automatisierte Tests, Upgrade-Behandlung und Betriebsdokumentation.

Softoft entwickelt Ihre Znuny-Generic-Interface-Erweiterung

Operationsdesign, Perl-Implementierung, Webservice-Konfiguration, Paketierung, Deployment, Tests und laufende Wartung.

Znuny-API-Programmierung anfragen

Buchen Sie ein 15-minütiges Gespräch, um Endpoints, Znuny-Version und angebundene Anwendung zu besprechen.

Häufig gestellte Fragen

Kann Znuny eigene REST-Endpoints bereitstellen?

Ja. Entwickeln Sie eine Generic-Interface-Operation, registrieren Sie das Modul in SysConfig, ergänzen Sie einen REST-Provider und liefern Sie die Dateien als Znuny-Paket aus.

Welche Paket- und Konfigurationswurzeln verwendet Znuny?

Das Paketmanifest verwendet otrs_package, SysConfig-XML verwendet otrs_config. Die Framework-Versionen müssen zu den tatsächlich unterstützten Znuny-Releases passen.

Kann Softoft eine individuelle Znuny-API-Erweiterung programmieren?

Ja. Softoft übernimmt Operationsdesign, Perl-Entwicklung, Webservice-Konfiguration, Paketierung, Tests, Deployment und Wartung.