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 stammen aus OpenTicketAIConnector (connector-code/): Controller TicketAICatalog, SysConfig in OpenTicketAIConnector.xml und Kernel::System::OpenTicketAIConnector::ZnunySetup. Katalogoperationen liefern Daten, die Standard-Ticketoperationen nicht abdecken. Controller und Webservice für Ihr eigenes Paket umbenennen.

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.

Kernel/GenericInterface/Operation/TicketAICatalog/Base.pm
package Kernel::GenericInterface::Operation::TicketAICatalog::Base;


use strict;
use warnings;


use Kernel::System::VariableCheck qw(IsHashRefWithData IsArrayRefWithData);
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)) {
        if ( !$Param{$Needed} ) {
            return {
                Success      => 0,
                ErrorMessage => "Got no $Needed!",
            };
        }
        $Self->{$Needed} = $Param{$Needed};
    }


    return $Self;
}


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


    my ( $UserID, $UserType ) = $Self->Auth(%Param);
    if ( !$UserID ) {
        return (
            undef,
            $Self->ReturnError(
                ErrorCode    => 'TicketAICatalog.AuthFail',
                ErrorMessage => 'Authentication failed!',
            ),
        );
    }
    return ( $UserID, undef );
}


sub _IsDropdownFieldType {
    my ( $Self, $FieldType ) = @_;


    return 0 if !$FieldType;
    return 1 if $FieldType eq 'Dropdown';
    return 1 if $FieldType eq 'Multiselect';
    return 1 if $FieldType eq 'Einzelauswahl';
    return 1 if $FieldType eq 'Mehrfachauswahl';
    return 0;
}


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“
Kernel/GenericInterface/Operation/TicketAICatalog/QueueList.pm
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}. Die Connector-Operation DynamicFieldValues prüft Pflichtfeld und Existenz vor dem Kernel-Aufruf:

# Kernel/GenericInterface/Operation/TicketAICatalog/DynamicFieldValues.pm (Auszug)
my $Name = $Data->{Name} // $Data->{DynamicFieldName} // '';
if ( !$Name ) {
    return $Self->ReturnError(
        ErrorCode    => 'TicketAICatalog.MissingName',
        ErrorMessage => 'Dynamic field Name is required.',
    );
}


my $FieldConfig = $Kernel::OM->Get('Kernel::System::DynamicField')->DynamicFieldGet( Name => $Name );
if ( !IsHashRefWithData($FieldConfig) ) {
    return $Self->ReturnError(
        ErrorCode    => 'TicketAICatalog.NotFound',
        ErrorMessage => "Dynamic field '$Name' not found.",
    );
}

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>:

Kernel/Config/Files/XML/OpenTicketAIConnector.xml
<?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">OTAI 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::OpenTicketAIConnector::ZnunySetup')->Install();
]]></CodeInstall>
<CodeReinstall Type="post"><![CDATA[
    $Kernel::OM->Get('Kernel::System::OpenTicketAIConnector::ZnunySetup')->Install();
]]></CodeReinstall>
<CodeUpgrade Type="post"><![CDATA[
    $Kernel::OM->Get('Kernel::System::OpenTicketAIConnector::ZnunySetup')->Install();
]]></CodeUpgrade>
<CodeUninstall Type="pre"><![CDATA[
    $Kernel::OM->Get('Kernel::System::OpenTicketAIConnector::ZnunySetup')->Uninstall();
]]></CodeUninstall>

Znuny-Setup liest SysConfig (OpenTicketAIConnector::AgentPassword muss vor der Installation gesetzt sein) und legt API-Agent plus Webservice an:

# Kernel/System/OpenTicketAIConnector/ZnunySetup.pm (Auszug)
sub Install {
    my ( $Self, %Param ) = @_;


    my $ConfigObject = $Kernel::OM->Get('Kernel::Config');
    my $LogObject    = $Kernel::OM->Get('Kernel::System::Log');


    my $Password = $ConfigObject->Get('OpenTicketAIConnector::AgentPassword') || '';
    if ( !$Password ) {
        $LogObject->Log(
            Priority => 'error',
            Message  => 'OpenTicketAIConnector: set OpenTicketAIConnector::AgentPassword in System Configuration before install.',
        );
        return;
    }


    my $UserLogin      = $ConfigObject->Get('OpenTicketAIConnector::AgentUserLogin') || 'open_ticket_ai';
    my $WebServiceName = $ConfigObject->Get('OpenTicketAIConnector::WebServiceName') || 'OpenTicketAI';
    ...
}

Bei Paket-Upgrades 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.

Znuny Automatisierung & Schnittstellen

Integrieren Sie Znuny nahtlos in Ihre IT-Systeme: Wir realisieren Webservices, Prozess-Workflows und REST-Konnektoren nach Ihren Anforderungen.

Automatisierung besprechen

Häufig gestellte Fragen

Wie kann ich eigene REST-Endpoints in Znuny bereitstellen?

Eine eigene REST-Endpoint-Bereitstellung in Znuny erfordert die Integration von vier Hauptkomponenten. Zuerst entwickeln Sie eine Perl-Operation, die die Logik für Ihre spezifische Aktion oder Datenabfrage enthält, Authentifizierung handhabt und Znuny-Kernel-APIs aufruft. Diese Operation muss ein stabiles JSON-Ergebnis liefern. Zweitens registrieren Sie diese Operation über SysConfig-XML, um sie in der Admin-Oberfläche sichtbar und konfigurierbar zu machen. Drittens definieren Sie in einer Webservice-YAML-Datei die Verbindung zwischen Ihrem Operationstyp, dem REST-Pfad und den unterstützten HTTP-Methoden. Schließlich bündeln Sie alle diese Dateien in einem Znuny-Paket, das die Installation und Aktualisierung der Webservice-Konfiguration automatisiert und einen konsistenten Lebenszyklus gewährleistet.Quellen:- Znuny REST API erweitern: eigene Generic-Interface-Operationen- GenericTicketConnectorREST - Znuny Documentation

Welche Konventionen gelten für Klassen- und Dateinamen bei Generic-Interface-Operationen?

Für Generic-Interface-Operationen in Znuny folgen Klassen- und Dateinamen einer spezifischen Konvention, um die Struktur und Auffindbarkeit zu gewährleisten. Die Klasse sollte dem Muster Kernel::GenericInterface::Operation::<Controller>::<Name> folgen, wobei <Controller> eine logische Gruppierung (z.B. TicketAICatalog) und <Name> die spezifische Operation (z.B. QueueList) darstellt. Die entsprechende Datei wird unter Kernel/GenericInterface/Operation/<Controller>/<Name>.pm abgelegt. Alle Operationsklassen müssen von Kernel::GenericInterface::Operation::Common erben, um grundlegende Funktionen wie Authentifizierung und strukturierte Fehlerbehandlung zu nutzen. Es ist zudem zwingend erforderlich, our $ObjectManagerDisabled = 1; in jeder dieser Operationsklassen zu deklarieren, um die korrekte Initialisierung im Znuny-Framework sicherzustellen.Quellen:- Znuny REST API erweitern: eigene Generic-Interface-Operationen- API — Znuny documentation

Wie registriere ich eine eigene Generic-Interface-Operation in der Znuny SysConfig?

Um eine eigene Generic-Interface-Operation in Znuny SysConfig zu registrieren, müssen Sie eine XML-Datei erstellen, die dem Znuny-/OTRS-Konfigurationsschema entspricht. Der relevante Einstellungspfad folgt dem Muster GenericInterface::Operation::Module###<Controller>::<Name>. In dieser XML-Datei, die typischerweise unter Kernel/Config/Files/XML/IhrPaketName.xml gespeichert wird, definieren Sie die Konfigurationseinträge. Es ist entscheidend, dass das XML-Dokument mit der Wurzel <otrs_config version="2.0" init="Application"> beginnt, um die Kompatibilität mit dem Znuny-Framework sicherzustellen. Diese Registrierung ermöglicht es Znuny, Ihre Operation zu erkennen und sie über die Admin-Oberfläche zu verwalten, sowie sie in Webservice-Konfigurationen zu referenzieren.Quellen:- Znuny REST API erweitern: eigene Generic-Interface-Operationen- Web Services - Znuny Documentation

Welche Schritte sind für die Entwicklung einer sicheren und wartbaren Znuny REST API-Erweiterung erforderlich?

Die Entwicklung einer sicheren und wartbaren Znuny REST API-Erweiterung umfasst mehrere integrale Schritte. Beginnen Sie mit der Perl-Backend-Entwicklung für die Operation, die robuste Authentifizierung, präzise Datenverarbeitung und eine stabile JSON-Antwort sicherstellt. Implementieren Sie dabei umfassende Eingabevalidierung und streben Sie, wo immer möglich, idempotentes Verhalten für schreibende Operationen an. Registrieren Sie die Operation anschließend in der SysConfig und konfigurieren Sie das REST-Routing über die Webservice-YAML-Datei, um die Endpunkte und HTTP-Methoden festzulegen. Ein entscheidender Schritt ist die Paketierung aller Komponenten in einem Znuny-Paket, um eine einfache Installation, Aktualisierung und Deinstallation zu ermöglichen. Abschließend sind umfassende Tests auf verschiedenen Znuny-Framework-Versionen unerlässlich, um Funktionalität, Sicherheit und Kompatibilität zu gewährleisten.Quellen:- Znuny REST API erweitern: eigene Generic-Interface-Operationen- Plugin-Entwicklung - Znuny Documentation

Wie gehe ich mit Authentifizierung und Fehlerbehandlung in meiner eigenen Znuny Operation um?

In eigenen Znuny Generic-Interface-Operationen wird die Authentifizierung und Fehlerbehandlung typischerweise über die Basisklasse Kernel::GenericInterface::Operation::Common gehandhabt, von der Ihre Operation erben sollte. Diese Basisklasse stellt die Methode Auth() bereit, die die Authentifizierung des aufrufenden Benutzers übernimmt und dessen UserID zurückgibt. Eine empfohlene Praxis ist die Implementierung einer Hilfsmethode wie _AuthOrError, die Auth() aufruft und bei einem Authentifizierungsfehler sofort eine strukturierte Fehlermeldung über ReturnError() zurückgibt. ReturnError() ist ebenfalls eine Methode der Basisklasse, die es Ihnen ermöglicht, konsistente Fehlerobjekte mit einem ErrorCode und einer ErrorMessage zu erzeugen, was die Fehlerbehandlung auf Client-Seite erheblich vereinfacht und die API-Stabilität erhöht.Quellen:- Znuny REST API erweitern: eigene Generic-Interface-Operationen- API — Znuny documentation

Was sind die Best Practices für das Lesen und Verarbeiten von Daten in einer Znuny Generic-Interface-Operation?

Beim Lesen und Verarbeiten von Daten in einer Znuny Generic-Interface-Operation sollten Sie mehrere Best Practices beachten, um Robustheit und Sicherheit zu gewährleisten. Eingehende Request-Felder sind über $Param{Data} zugänglich. Es ist entscheidend, alle empfangenen Daten umfassend zu validieren, bevor sie an Znuny-Kernel-APIs weitergegeben werden. Nutzen Sie Funktionen wie Kernel::System::VariableCheck::IsHashRefWithData oder IsArrayRefWithData, um die Struktur und Existenz von Daten zu prüfen. Überprüfen Sie Pflichtfelder und stellen Sie sicher, dass die Werte den erwarteten Typen und Formaten entsprechen. Für lesende Katalogoperationen ist dies besonders wichtig, um unerwartete Eingaben abzufangen. Bei schreibenden Operationen ist eine noch strengere Validierung und gegebenenfalls die Implementierung von idempotentem Verhalten ratsam, um Seiteneffekte bei mehrfachen Aufrufen zu minimieren.Quellen:- Znuny REST API erweitern: eigene Generic-Interface-Operationen- Znuny REST API

Welche Aspekte sind beim Testen einer neuen Znuny REST API-Operation wichtig?

Beim Testen einer neuen Znuny REST API-Operation ist ein umfassender Ansatz entscheidend, um die Zuverlässigkeit und Sicherheit zu gewährleisten. Testen Sie nicht nur auf erfolgreiche Responses mit gültigen Eingaben, sondern auch auf verschiedene Fehlerzustände. Dazu gehören Authentifizierungsfehler (z.B. ungültige Anmeldeinformationen), fehlende Queue-Rechte oder andere Berechtigungsprobleme, ungültige Eingaben (fehlende Pflichtfelder, falsche Datentypen) und Szenarien mit leeren Daten oder unerwarteten Werten. Überprüfen Sie auch die Response-Größe und -Struktur, um sicherzustellen, dass die API konsistente und erwartete Ergebnisse liefert. Ein weiterer wichtiger Aspekt ist die Reinstallation des Pakets, um sicherzustellen, dass der Upgrade-Pfad funktioniert und keine Konfigurationen verloren gehen. Führen Sie diese Tests idealerweise auf jeder angegebenen Znuny-Framework-Version durch, die Ihr Paket unterstützen soll, um Kompatibilitätsprobleme frühzeitig zu erkennen.Quellen:- Znuny REST API erweitern: eigene Generic-Interface-Operationen- Web Services - Znuny Documentation