Znuny Web Services – REST API

Znuny Web Services – REST API

In dieser detaillierten Anleitung erfahren Sie, wie Sie die Znuny REST API (Teil des Generic Interface) aktivieren, konfigurieren und in Ihre eigenen Anwendungen integrieren können.

1. Architektur & Grundprinzipien

Znuny stellt sein Generic Interface über REST- und SOAP-Webservices zur Verfügung. Die REST API kommuniziert über HTTP(S) mit JSON-Datenformat und ermöglicht:

• Ticket-Verwaltung: Erstellen, Abrufen, Ändern, Löschen
• Artikel-Verwaltung: Artikel hinzufügen, Anhänge verwalten
• Historie & Suche: Ticket-Verlauf einsehen und komplexe Suchabfragen durchführen

Wichtiger Hinweis: Eine Standardinstallation enthält keine vorkonfigurierten Webservices – diese müssen im Admin-Bereich unter „Prozesse & Automation → Web Services” manuell angelegt werden.

2. Konfiguration

2.1 Generic Interface aktivieren

1. Navigieren Sie im Admin-Bereich zu SysConfig → GenericInterface.Transport und wählen Sie REST (HTTP).
2. Unter AdminGenericInterfaceTransportHTTPREST konfigurieren Sie Timeouts, Host-Header und Debug-Level.
3. In GenericInterface.Operation legen Sie die gewünschten Operationen an (z. B. TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete, TicketHistoryGet) und aktivieren diese.

2.2 Basis-URL & Authentifizierung

• Basis-URL

  TicketCreate

• Authentifizierung

  • Znuny-Session-Cookies
  • API-Keys / Token (über SysConfig konfigurierbar)
  • Verwenden Sie immer HTTPS für sichere Übertragungen!

3. Endpunkte & HTTP-Methoden (Detailübersicht)

Für jeden Endpunkt finden Sie hier eine ausführliche Darstellung zu Parametern, möglichen Antworten und praxisnahen Beispielen.

3.1 TicketCreate (POST)

URL: /Webservice/<ServiceName>/TicketCreate Methode: POST

Beschreibung: Erstellt ein neues Ticket und legt gleichzeitig einen ersten Artikel an.

Parameter	Typ	Pflicht	Beschreibung
SessionID	Integer	Ja¹	Session-ID oder UserLogin+Password
UserLogin	String	Ja²	Agenten-Login (in Kombination mit Password)
Password	String	Ja²	Passwort (in Kombination mit UserLogin)
Ticket.Title	String	Ja	Betreff des Tickets
Ticket.Queue	String	Ja	Warteschlangen-Name oder Ticket.QueueID
Ticket.State	String	Ja	Anfangsstatus (z. B. new)
Ticket.Priority	String	Ja	Priorität (z. B. 3 normal)
Ticket.CustomerUser	String	Ja	Kunden-E-Mail oder Login
Article.Subject	String	Ja	Betreff des ersten Artikels
Article.Body	String	Ja	Inhalt des ersten Artikels
Article.MimeType	String	Ja	text/plain oder text/html

¹ Entweder SessionID ODER UserLogin+Password erforderlich. ² Wenn kein SessionID-Token vorliegt.

Beispiel Request:

TicketSearch

Beispiel Antwort:

TicketGet

3.2 TicketSearch (GET)

URL: /Webservice/<ServiceName>/TicketSearch Methode: GET

Beschreibung: Durchsucht Tickets anhand verschiedenster Filterkriterien.

Parameter	Typ	Pflicht	Beschreibung
UserLogin, Password	String,String	Ja¹	Agenten-Credentials oder SessionID²
SessionID	Integer	Ja²	Token für authentifizierte Sitzungen
Title	String/String[]	Nein	Wildcard-Suche im Titel (%Bestellung%)
TicketNumber	String/String[]	Nein	Ticketnummer(n)
QueueIDs	Integer[]	Nein	Warteschlangen-IDs
States	String[]	Nein	Status (new, open, …)
StateType	String/String[]	Nein	Open/Closed-Kategorie
DynamicField_Name.Op	Mixed	Nein	Dynamische Felder mit Operator (Equals, Like, GreaterThan …)

¹ Entweder UserLogin+Password ODER SessionID. ² Wenn kein Login-Paar übergeben wird.

Beispiel Request:

TicketUpdate

Beispiel Antwort:

TicketDelete

3.3 TicketGet (GET)

URL: /Webservice/<ServiceName>/TicketGet Methode: GET

Beschreibung: Ruft detaillierte Ticket-Daten inklusive Artikel, Anhängen und dynamischen Feldern ab.

Parameter	Typ	Pflicht	Beschreibung
UserLogin, Password	String,String	Ja¹	Agenten-Credentials oder SessionID²
SessionID	Integer	Ja²	Token für authentifizierte Sitzungen
TicketID	String/String[]	Ja	Eine oder mehrere Ticket-IDs (komma-getrennt oder Array)
DynamicFields	Boolean (0/1)	Nein	1 = Dynamische Felder im Ergebnis, Standard = 0
Extended	Boolean	Nein	1 = Erweiterte Metadaten (z. B. FirstResponse)
AllArticles	Boolean	Nein	1 = Alle Artikel zurückliefern
ArticleLimit	Integer	Nein	Max. Anzahl der zurückgegebenen Artikel
Attachments	Boolean	Nein	1 = Anhänge in Base64 einbetten
GetAttachmentContents	Boolean	Nein	1 = Inhalte der Anhänge ebenfalls laden
HTMLBodyAsAttachment	Boolean	Nein	1 = HTML-Version des Artikels als Attachment anfügen

¹ Entweder UserLogin+Password ODER SessionID. ² Wenn kein Login-Paar übergeben wird.

Beispiel Request:

TicketHistoryGet

Beispiel Antwort (gekürzt):

/Webservice/<ServiceName>/TicketCreate

3.4 TicketUpdate (PUT)

URL: /Webservice/<ServiceName>/TicketUpdate Methode: PUT

Beschreibung: Aktualisiert Felder eines bestehenden Tickets und kann optional einen neuen Artikel erstellen.

Parameter	Typ	Pflicht	Beschreibung
SessionID	Integer	Ja¹	Token oder UserLogin+Password²
TicketID	Integer	Ja	ID des zu aktualisierenden Tickets
Ticket.Title	String	Nein	Neuer Titel
Ticket.State	String	Nein	Neuer Status
Ticket.Owner	String/ID	Nein	Neuer Besitzer
Ticket.PendingTime	Hash / Diff	Nein	Neue Pending-Zeit
Article.Subject	String	Nein	Erstellt einen neuen Artikel
Article.Body	String	Nein	Inhalt des neuen Artikels
DynamicField…	Array	Nein	Dynamische Felder aktualisieren
Attachment…	Array	Nein	Neue Anhänge hinzufügen

¹ Entweder SessionID ODER UserLogin+Password. ² Wenn kein SessionID-Token vorliegt.

Beispiel Request:

POST

Beispiel Antwort:

new

3.5 TicketDelete (DELETE)

URL: /Webservice/<ServiceName>/TicketDelete Methode: DELETE

Beschreibung: Löscht ein oder mehrere Tickets endgültig.

Parameter	Typ	Pflicht	Beschreibung
SessionID	Integer	Ja¹	Token oder UserLogin+Password²
TicketID	String/Array	Ja	Ein oder mehrere Ticket-IDs

Beispiel Request:

3 normal

Beispiel Antwort:

text/plain

3.6 TicketHistoryGet (GET)

URL: /Webservice/<ServiceName>/TicketHistoryGet Methode: GET

Beschreibung: Ruft die Historie eines oder mehrerer Tickets ab.

Parameter	Typ	Pflicht	Beschreibung
SessionID	Integer	Ja¹	Token oder UserLogin+Password²
TicketID	String/Array	Ja	Ein oder mehrere Ticket-IDs

Beispiel Request:

text/html

4. Erweiterung & Anpassung

4.1 WADL-Definition

Neue Ressourcen in der WADL-Datei definieren:

/Webservice/<ServiceName>/TicketSearch

4.2 YAML-Import

Alternativ können Sie Operationen per YAML definieren:

GET

---

5. Fehlerbehandlung & Logging

• Erfolgsindikator: Success: 0|1
• Fehlermeldung: ErrorMessage im JSON
• Debugging: Setzen Sie im Transport-Dialog Debug-Level auf Debug → Log-Einträge werden in der Datenbank sichtbar

---

6. Anwendungsfälle

Szenario	Beschreibung
Systemübergreifende Automatisierung	Tickets aus Monitoring-Tools (Nagios, Zabbix) erstellen
Datensynchronisation	Batch-Updates von Ticket-Feldern aus externem CRM
Self-Service-Portale	Kunden legen eigene Tickets via REST an
Mobile Apps	Native iOS/Android-Apps kommunizieren per REST

---

Fazit

Die Znuny REST API ist flexibel, performant und dank Generic Interface hochgradig erweiterbar. Ob einfache Ticket-Erstellung oder komplexe Workflow-Automatisierung – mit wenigen Schritten im Admin-Bereich und Standard-JSON-Requests realisieren Sie nahtlose Integrationen in jede IT-Landschaft.