Zum Inhalt springen
Znuny Logo Znuny Community Docs

Znuny Web Services – REST API

Einführung in externe Schnittstellenintegration

Abschnitt betitelt „Einführung in externe Schnittstellenintegration“

In einer weltweit vernetzten digitalen Umgebung müssen Ticketsysteme automatisiert auf Anfragen anderer Systeme reagieren und gleichzeitig Daten oder Anfragen an externe Dienste senden können. Znuny, das leistungsstarke Open-Source-Ticketsystem, adressiert diese Anforderung mit seinem Generic Interface. Es ermöglicht Administratoren, auch ohne umfassende Programmierkenntnisse, Webdienste für vielfältige Aufgaben zu konfigurieren. Znuny unterstützt die Kommunikation über REST- und SOAP-Protokolle und ermöglicht die nahtlose Integration mit:

  • CRM-Systemen
  • Projektmanagement-Tools
  • Dokumentenmanagementsystemen
  • und vielen weiteren Anwendungen

Ein Webdienst fungiert als Brücke zwischen Znuny und externen Systemen. Dabei definieren Operationen und Invoker die Kommunikationsrichtung, während Mapping und Transport festlegen, wie Daten übertragen und interpretiert werden. Mit Znuny können Sie Webdienste konfigurieren, um intern Aktionen auszuführen, Anfragen auf Remote-Systemen zu initiieren, Datenkonversionen zwischen Systemen zu managen und das Kommunikationsprotokoll festzulegen.

Der Zugang zu den Web-Services befindet sich im Modul Web Services der Gruppe Prozesse & Automation.

Eine frische Installation von Znuny enthält standardmäßig keine vorkonfigurierten Web-Services. Die folgende Dokumentation illustriert, wie Webdienste erstellt, bearbeitet, gelöscht, geklont, exportiert und importiert werden können, sowie den Einsatz des Debugger-Tools.

Implementierung der Schnittstellen

Abschnitt betitelt „Implementierung der Schnittstellen“

Die Implementierung von Web-Services in Znuny ermöglicht eine flexible und dynamische Integration Ihrer Geschäftsprozesse mit zahlreichen externen Tools und Systemen. Durch die Erstellung und Nutzung dieser Services wird die Effizienz gesteigert, indem manuelle Eingriffe reduziert und die Antwortzeiten auf Kundenanfragen verkürzt werden. Darüber hinaus sorgt die Vielseitigkeit des Generic Interface dafür, dass Znuny nahezu unbegrenzt erweiterbar ist und sich somit perfekt in bestehende IT-Landschaften einfügt.

Sicherheit und Konfiguration

Abschnitt betitelt „Sicherheit und Konfiguration“

Bei der Konfiguration und Sicherheit von Webdiensten ist zu beachten, dass bei einem Export alle gespeicherten Passwörter im Klartext mitexportiert werden. Die Aufbewahrung und der Umgang mit Passwörtern sollten daher mit besonderer Sorgfalt behandelt werden.

Für detaillierte Informationen zur systeminternen Konfiguration, wie zum Beispiel die Konfigurationsmöglichkeiten von Cache und Frontend-Modulen, empfehlen wir die offizielle Znuny-Systemkonfigurationsdokumentation zu konsultieren.

Dokumentation der Anbindungen

Abschnitt betitelt „Dokumentation der Anbindungen“

Webdienste bieten in einer zunehmend digitalisierten Betriebsumgebung die Möglichkeit, Znuny mit anderen Systemen und Diensten zu verknüpfen. Das Gewährleisten einer effizienten und sicheren Kommunikation bedeutet daher, Webdiensteinstellungen im Vorfeld präzise zu konfigurieren. Im Folgenden werden die Grundlagen der Einstellungen für Webdienste in Znuny detaillierter erläutert, um Ihnen eine umfassende Handlungsanleitung zu bieten.

Allgemeine Schnittstellen-Einstellungen

Abschnitt betitelt „Allgemeine Schnittstellen-Einstellungen“
  • Name*
    • Der Name identifiziert den Webdienst eindeutig innerhalb von Znuny. Es ist wichtig, einen klaren und beschreibenden Namen zu wählen, der die Funktion oder den Partner reflektiert, mit dem interagiert wird.
  • Beschreibung
    • Ein erweiterter Kommentar, der den Zweck und die Funktionalität des Webdienstes detailliert darstellt. Dies erleichtert die Übersichtlichkeit und Wartbarkeit.
  • Remote-System
    • Ermöglicht es, den Namen des externen Systems festzulegen, mit dem Znuny interagiert.
  • Debug-Schwellenwert
    • Wählen Sie, wie ausführlich die Protokollierung der Kommunikation erfolgen soll. Die Einstellungen reichen von Debug (detaillierteste Protokollierung) bis zu Fehler (nur Fehlermeldungen).
  • Gültigkeit
    • Bestimmt, ob der Webdienst aktiviert (gültig) oder deaktiviert (ungültig, vorübergehend ungültig) ist. Nur gültige Webdienste werden von Znuny ausgeführt.

Netzwerktransport - SOAP oder REST

Abschnitt betitelt „Netzwerktransport - SOAP oder REST“

Für die Implementierung der Integration mit anderen Systemen bieten sich unterschiedliche Protokolle an. Hierbei ist die Wahl des Netzwerktransports grundlegend:

  • Netzwerktransport
    • Wählen Sie zwischen HTTP::REST und HTTP::SOAP. Diese Protokolle definieren, wie die Datenübertragung zwischen dem Znuny Ticketsystem und dem verbundenen System erfolgt.
  • Operation hinzufügen
    • Ermöglicht es, spezifische Aktionen, sogenannte Operationen, für den Webdienst zu definieren. Hierbei können Sie aus einer Vielzahl von vordefinierten Operationen wählen, wie beispielsweise Ticket::TicketCreate zum Anlegen von Tickets.

Erstellung eines Tickets via REST

Abschnitt betitelt „Erstellung eines Tickets via REST“

Ein praktisches Beispiel verdeutlicht den Wert von Webdiensten in Znuny. Über das HTTP::REST-Protokoll lässt sich die Operation Ticket::TicketCreate einrichten. Die definierten Routen ermöglichen es externen Systemen, mithilfe von HTTP-POST-Requests Tickets in Znuny zu erstellen. Hierdurch werden neue Dimensionen der Automatisierung und Integration realisiert, was Prozesseffizienz und Kundenzufriedenheit bedeutend steigern kann.

Sicherheitshinweis

Abschnitt betitelt „Sicherheitshinweis“

Beachten Sie, dass bei Exporten der Webdiensteinstellungen Passwörter im Klartext exportiert werden können. Es ist daher essenziell, sensible Informationen geschützt zu behandeln und Sicherheitsbestimmungen zu beachten.

Die effektive Nutzung von Webdiensten in Znuny ermöglicht es Unternehmen, ihre Arbeitsabläufe intelligenter und agiler zu gestalten. Durch die präzise Konfiguration der Webdiensteinstellungen wird eine solide Grundlage geschaffen, die es erlaubt, Znuny nahtlos in das digitale Ökosystem eines Unternehmens zu integrieren.

Webdiensteinstellungen und -operationen in Znuny

Abschnitt betitelt „Webdiensteinstellungen und -operationen in Znuny“

Die Integration externer Systeme mit Znuny über Webdienste ist ein essentieller Bestandteil, um ein effizientes Ticketmanagement zu gewährleisten. Diese Integration wird durch die Definition verschiedener Operationen ermöglicht, die spezifische Aktionen im Rahmen des Ticketlebenszyklus ausführen können. Ein wesentlicher Teil dieser Integration ist das Verständnis der notwendigen Attribute für jede Operation sowie die Verwendung von Standards für die Datenübertragung.

Erforderliche Attribute für die Schnittstellenoperationen

Abschnitt betitelt „Erforderliche Attribute für die Schnittstellenoperationen“

Für die grundlegenden Ticketoperationen in Znuny werden spezifische Attribute benötigt. Die wichtigsten Operationen umfassen:

  • TicketCreate: Erstellt ein neues Ticket mit zugehörigem Artikel
  • TicketGet: Ruft detaillierte Informationen zu einem oder mehreren Tickets ab
  • TicketUpdate: Aktualisiert bestehende Ticket-Daten
  • TicketSearch: Durchsucht Tickets anhand definierter Kriterien
  • TicketHistoryGet: Ruft die Historie eines Tickets ab

Diese Operationen ermöglichen es Entwicklern, Anpassungen präzise durchzuführen und sicherzustellen, dass alle Anfragen die notwendigen Informationen enthalten, um erfolgreich bearbeitet zu werden.

Verwendung von XSLT für die Datenübertragung

Abschnitt betitelt „Verwendung von XSLT für die Datenübertragung“

Die XSLT-Transformation ist eine leistungsstarke Technik, um eingehende Daten aus Webservice-Anfragen in eine für Znuny verarbeitbare Form zu übertragen. Legen Sie dafür beispielsweise ein dynamisches Feld RemoteTicketID für Tickets an und mappen Sie in der jeweiligen Operation den Wert des eingehenden Attributs incidentID per XSLT in dieses Feld.

Webdiensteinstellungen: Requester (Anforderer)

Abschnitt betitelt „Webdiensteinstellungen: Requester (Anforderer)“

Für die Implementierung von Webdienstprozeduren als Requester bietet Znuny die Auswahl zwischen den Protokollen HTTP::REST und HTTP::SOAP. Hierbei ist die Auswahl des Netzwerktransports elementar, um eine ordnungsgemäße Verbindung mit dem externen System sicherzustellen. Nach Auswahl des Transports muss die Konfiguration gespeichert und entsprechend den spezifischen Anforderungen angepasst werden.

Die Einrichtung eines Fehlerbehandlungsmoduls ist ebenso ein wichtiger Schritt, um eine robuste Kommunikation zu garantieren. Znuny ermöglicht es, dafür spezifische Module zu implementieren und zu konfigurieren.

Zusammenfassung und weiterführende Schritte

Abschnitt betitelt „Zusammenfassung und weiterführende Schritte“

Indem Znuny eine vielseitig konfigurierbare API für Webdienste bereitstellt, eröffnet es eine Welt der Möglichkeiten für die Integration und Automatisierung von Ticketmanagementprozessen. Durch die Bereitstellung genauer Spezifikationen und die Verwendung von Standards wie XSLT für die Datenmanipulation bietet Znuny seinen Nutzern eine flexible Basis für die Erweiterung ihrer Ticketingsysteme im Einklang mit ihren spezifischen Geschäftsanforderungen.

Egal ob als Provider oder Requester, die präzise Bearbeitung von Webdiensteinstellungen sichert eine nahtlose und effiziente Kommunikation mit externen Systemen und Diensten.

Best Practices

Abschnitt betitelt „Best Practices“
  • Authentifizierung sichern: Verwenden Sie immer HTTPS und API-Keys für Produktivumgebungen
  • Fehlerbehandlung implementieren: Richten Sie dedizierte Error-Handler für kritische Operationen ein
  • Logging aktivieren: Nutzen Sie Debug-Logging während der Entwicklung und deaktivieren Sie es in Produktion
  • Versionierung: Dokumentieren Sie Änderungen an Webservice-Konfigurationen für bessere Nachvollziehbarkeit
  • Testen: Testen Sie alle Operationen gründlich in einer Testumgebung, bevor Sie sie produktiv schalten

Mit einer sorgfältigen Konfiguration der Znuny Web Services schaffen Sie die Grundlage für eine erfolgreiche Integration in Ihre IT-Landschaft und profitieren von automatisierten, effizienten Geschäftsprozessen.

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

Wo verwalte ich Web Services in Znuny und was sind die ersten Schritte?

Web Services in Znuny werden zentral im Modul Web Services verwaltet, das sich in der Gruppe Prozesse & Automation befindet. Nach einer frischen Installation sind standardmäßig keine Web Services vorkonfiguriert, daher müssen Sie diese selbst anlegen. Dieses Modul bietet die Möglichkeit, bestehende Services zu bearbeiten, zu löschen, zu klonen, zu exportieren und zu importieren. Zudem steht ein Debugger-Tool zur Verfügung, um die Kommunikation zu überwachen und Fehler zu beheben. Die Konfiguration eines Webdienstes umfasst die Definition von Operationen und Invokern, die festlegen, wie Daten übertragen und interpretiert werden, um eine nahtlose Integration zu gewährleisten.

Quellen

Was ist der Unterschied zwischen Operationen und Invokern bei Znuny Web Services?

In Znuny Web Services spielen Operationen und Invoker unterschiedliche, aber komplementäre Rollen bei der Kommunikation mit externen Systemen. Operationen sind dafür zuständig, eingehende Aufrufe zu verarbeiten, wenn Znuny als Provider agiert. Das bedeutet, ein externes System sendet eine Anfrage an Znuny, und eine definierte Operation führt die entsprechende Aktion innerhalb von Znuny aus, wie zum Beispiel das Erstellen eines Tickets. Invoker hingegen senden ausgehende Anfragen an Remote-Systeme, wenn Znuny als Requester fungiert. Hierbei initiiert Znuny eine Kommunikation mit einem externen Dienst, um beispielsweise Daten abzurufen oder eine Aktion in einem anderen System auszulösen. Beide Komponenten sind entscheidend für die bidirektionale Integration und die Definition der Kommunikationsrichtung.

Quellen

Wie ermöglichen Znuny Web Services die Integration mit externen Systemen?

Znuny Web Services, basierend auf dem Generic Interface, ermöglichen eine nahtlose Integration mit einer Vielzahl externer Systeme wie CRM-Systemen, Projektmanagement-Tools und Dokumentenmanagementsystemen. Sie fungieren als Brücke, die eine automatisierte Kommunikation und Datenübertragung zwischen Znuny und diesen Diensten ermöglicht. Durch die Unterstützung von REST- und SOAP-Protokollen können Administratoren Webdienste konfigurieren, um intern Aktionen auszuführen, Anfragen auf Remote-Systemen zu initiieren, Datenkonversionen zu managen und Kommunikationsprotokolle festzulegen. Dies steigert die Effizienz, reduziert manuelle Eingriffe und verbessert die Antwortzeiten, indem Znuny flexibel in bestehende IT-Landschaften eingebunden wird und somit die Geschäftsprozesse optimiert.

Quellen

Welche allgemeinen Einstellungen sind für die Konfiguration eines Znuny Web Services wichtig?

Bei der Konfiguration eines Znuny Web Services sind mehrere allgemeine Einstellungen von Bedeutung, um dessen Funktion und Wartbarkeit zu gewährleisten. Der Name identifiziert den Webdienst eindeutig innerhalb von Znuny und sollte dessen Funktion oder den Partner widerspiegeln, mit dem interagiert wird. Eine detaillierte Beschreibung erläutert Zweck und Funktionalität des Webdienstes. Das Remote-System benennt das externe System, mit dem interagiert wird. Der Debug-Schwellenwert legt die Ausführlichkeit der Protokollierung fest, von Debug (sehr detailliert) bis Fehler (nur Fehlermeldungen). Schließlich bestimmt die Gültigkeit, ob der Webdienst aktiv ist (gültig) oder deaktiviert (ungültig, vorübergehend ungültig). Nur gültige Dienste werden von Znuny ausgeführt und verarbeiten Anfragen.

Quellen

Wie kann ich ein Ticket in Znuny über die REST API erstellen?

Das Erstellen eines Tickets in Znuny über die REST API ist ein praktisches Beispiel für die Nutzung von Web Services und wird durch die Operation Ticket::TicketCreate ermöglicht, die über das HTTP::REST-Protokoll eingerichtet werden kann. Externe Systeme können dann HTTP-POST-Requests an die definierten Routen senden, um neue Tickets in Znuny anzulegen. Hierfür müssen die erforderlichen Attribute für die TicketCreate-Operation im Request-Body als JSON-Payload übermittelt werden. Dies ermöglicht eine hohe Automatisierung und Integration, wodurch Prozesseffizienz und Kundenzufriedenheit erheblich gesteigert werden können, da Tickets direkt aus anderen Anwendungen generiert werden, ohne manuelle Eingriffe.

Quellen

Welche Sicherheitsaspekte sind bei der Konfiguration von Znuny Web Services zu beachten?

Bei der Konfiguration und dem Umgang mit Znuny Web Services sind wichtige Sicherheitsaspekte zu beachten, insbesondere im Hinblick auf Passwörter. Es ist essenziell zu wissen, dass beim Export von Webdiensteinstellungen alle gespeicherten Passwörter im Klartext mitexportiert werden. Dies erfordert äußerste Sorgfalt bei der Aufbewahrung und dem Umgang mit diesen Exportdateien. Sensible Informationen sollten stets geschützt behandelt und die geltenden Sicherheitsbestimmungen eingehalten werden, um unbefugten Zugriff zu verhindern. Für eine umfassende systeminterne Konfiguration, einschließlich Cache- und Frontend-Modulen, wird zudem empfohlen, die offizielle Znuny-Systemkonfigurationsdokumentation zu konsultieren, um optimale Sicherheit zu gewährleisten und potenzielle Schwachstellen zu minimieren.

Quellen

Welche Kernoperationen stehen für das Ticketmanagement über Znuny Web Services zur Verfügung?

Für das Ticketmanagement über Znuny Web Services stehen mehrere grundlegende Operationen zur Verfügung, die eine umfassende Interaktion mit dem Ticketsystem ermöglichen. Zu den wichtigsten gehören:

  • TicketCreate: Diese Operation wird verwendet, um ein neues Ticket zusammen mit einem zugehörigen Artikel im System zu erstellen.
  • TicketGet: Mit dieser Operation können detaillierte Informationen zu einem oder mehreren spezifischen Tickets abgerufen werden.
  • TicketUpdate: Ermöglicht die Aktualisierung bestehender Ticket-Daten, wie z.B. Status, Priorität oder zugewiesener Agent.
  • TicketSearch: Diese Operation dient dazu, Tickets basierend auf bestimmten Kriterien zu durchsuchen und eine Liste der passenden Tickets zurückzugeben.
    Diese Operationen bilden die Basis für die Automatisierung von Ticketprozessen und die nahtlose Integration mit externen Systemen, wodurch die Effizienz im Kundenservice erheblich gesteigert wird.

Quellen