🔌 Zammad API Adapter (de)

‼️

Disclaimer: Dieser Text wurde ursprünglich für den TEQLY-Blog verfasst. Er kann im Original hier nachgelesen werden: Artikel

tl:dr

Wir haben aus Eigeninteresse einen Adapter für unser Ticketing-Tool Zammad in Javascript geschrieben und diesen gemäss dem open-source Gedanke mit NPM gepublished; Ihn also für Jede:n gratis zur Verfügung gestellt. Hier der Link zum Adapter

Organisiert dank Zammad

Um Supportanfragen zu Erfassen und Verwalten, verwenden wir bei TEQLY eine open-source Software namens Zammad. Falls ein Kunde ein Supportanliegen hat, kann er auf unsere Support-Email eine Nachricht senden und in Zammad wird ein Ticket dafür eröffnet. Für uns ist das unglaublich praktisch. So sehen alle immer welche Anfragen gerade zu beantworten sind und wir können die Aufgaben nach Expertisen unter uns verteilen. Zammad bietet ausserdem die Möglichkeit Tickets selber zu erfassen oder via API zu erstellen. Was eine API ist hat mein Kollege Andreas vor ein paar Wochen in einem Blog Artikel beschrieben.

Es begann bei EASIT.rent

Vor einigen Wochen sind wir mit unserem Rental-Service "EASIT - IT einfach einfach" gestartet. Dafür haben wir eigens eine Website mit Gatsby, einem static-website-generator Framework welches auf React aufbaut, geschrieben. Gatsby hat den Vorteil, dass es besonders schnell, sicher und skalierbare websiten erstellt. Dass wir bei TEQLY bereits ziemlich gut im Umgang mit React sind hat auch eine Rolle gespielt. Nun hat sich folgende Frage gestellt: Wie treten die potentiellen Kunden mit uns in Kontakt? Natürlich heisst die Antwort Kontaktformular. Nur wohin sollen diese Anfragen gehen? Natürlich nach Zammad. Doch wie binden wir Zammad in unsere Website ein?

Fehlende Offizielle Unterstützung

Leider gibt es seitens Zammad keine offizielle Unterstützung für Javascript. Javascript ist die Programmiersprache in welcher mit Gatsby Websites gebaut werden. Offiziell unterstützt werden lediglich Ruby & PHP. Weiter gibt es von Drittparteien Clients für Python, .NET, Android und Golang. Von Javascript ist auf der Website jedoch nichts zu lesen. Das muss aber noch nichts heissen. Schliesslich ist nicht ausgeschlossen, dass es schon vor uns ein*e Entwickler*In gab, welcher das Problem für uns bereits gelöst hat. Erste Anlaufstelle für Softwarepackete in Javascript ist das NPM Verzeichnis. NPM steht für Node Package Manager und ist ebenfalls die Quelle von welcher wir Gastsby und React bezogen haben. Der Node Package Manager verwaltet und versioniert Software-Abhängigkeiten und baut die fertige Software zusammen. NPM orientiert sich dabei an einer Datei welche package.json heisst. Die Abhängigkeiten oder Dependencies der EASIT Seite sehen wie folgt aus.

Von der Arbeit anderer profitieren...

Tatsächlich! Das Problem scheint bereits jemand gelöst zu haben. Auf npmjs.com findet sich ein Packet mit dem namen Zammad JS API Implementation. Es gibt aber zwei Probleme: Das Package wurde zuletzt vor 2 Jahren geupdated. Das muss im Prinzip nichts schlechtes heissen, stiftet aber nicht wirklich Vertrauen. Ebenfalls ist das Package eher schlecht dokumentiert und zieht zwei weitere Dependencies an. Schlussendlich benötigen wir gar nicht einen vollen Zammad JS API Client. Wir wollen lediglich Tickets erstellen können. Das muss einfacher gehen! Wir schreiben den Adapter also selber. Im Internet finden sich dazu einige Ansätze. Es dauert hingegen doch fast einen ganzen Nachmittag, bis das erste Ticket via API in Zammad erscheint. Doch damit ist der Durchstich geschafft.

Wiederverwendung im Sicherheitscheck

Für eine Marketingkampagne haben wir uns dazu entschieden, einen Sicherheitscheck für KMU's zu schreiben. Auch dieses Projekt wurde wieder mit Gatsby umgesetzt. Um schnell und einfach Umfragen zu erstellen verwenden wir ausserdem dieses Mal das SurveyJS Framework. Das Resultat kann sich sehen lassen:

Die Resultate des Check verlassen den Browser nicht.
Wer am Ende eine Beratung wünscht, kann seine Kontaktdaten angeben, damit wir kontakt aufnehmen können. Damit die Antworten nicht im Nirvana verschwinden, soll also wieder ein Ticket erstellt werden. Mit einer kleinen Anpassung ist der EASIT Adapter in kürze für das neue Vorhaben angepasst und in Betrieb.

Release als Package

Damit wir den Adapter auch in zukünftigen Projekten verwenden können, haben wir ihn noch einmal ein wenig generischer umgeschrieben. So kann er nun in jedes Javascript-Projekt eingebunden werden. Man erstellt ein neues Objekt der Klasse ZammadTicketCreator und initialisiert es mit der Server URL der Zammad Instanz, einem fingerprint (aus Sicherheitsgründen) und einer Source (Diese bestimmt den Titel des erstellten Zammad-Tickets).
Das erstellte Objekt besitzt eine send() methode, welche ein Ticket erstellt. Das sieht in der Praxis wie folgt aus:

const ZammadTicketCreator = new ZammadTicketCreator(serverUrl, fingerprint, source)

ZammadTicketCreator.send("Customer Name","test@email.com", {this: "test"})

Bei TEQLY arbeiten wir vorwiegend mit open-source Projekten. Wir sind froh, können wir vom geistigen Eigentum anderer profitieren. Aus diesem Grund möchten wir ab und an auch etwas zurück geben. Vielleicht stösst ja in naher Zukunft jemand Anders auf das gleiche Problem oder will den Adapter weiterentwickeln. Der Adapter ist frei zum Download im NPM Verzeichnis.