API-Referenz

Für die meisten Benutzer sind die Beispielskripte aus dem Einrichtungsanleitung völlig ausreichend. Wenn Sie jedoch eine feinere Steuerung wünschen, z.B. um Tickets mit hoher und niedriger Priorität für verschiedene Arten von Systemereignissen zu erstellen, müssen Sie die Daten, die diese Skripte an Zammad senden, anpassen.

Beispiel

Dieses benutzerdefinierte Skript setzt alle Tickets, die es erstellt, automatisch auf hohe Priorität und weist sie charlie@chrispresso.com zu.

#!/bin/bash

curl -X POST \
  -F "event_id=$NOTIFY_HOSTPROBLEMID" \
  -F "host=$NOTIFY_HOSTNAME" \
  -F "state=$NOTIFY_HOSTSTATE" \
  -F "text=$NOTIFY_HOSTOUTPUT" \
  -F "priority=3 high" \
  -F "owner=charlie@chrispresso.com" \
  https://zammad.example.com/api/v1/...

Wie funktioniert das?

Es gibt zwei Arten von Daten, die Sie an die API übergeben können, beide in Form von Schlüssel-Wert-Paaren:

Checkmk-Parameter

sind erforderlich und bilden den Inhalt der resultierenden Tickets/Artikel. Sie bestimmen auch, ob ein Ereignis ein neues Ticket erstellt oder ein bestehendes aktualisiert/schließt.

Dies sind die einzigen Werte, die in den Beispielskripten verwendet werden. Verwenden Sie sie am besten genau so. Sie können auch angepasst werden, aber uns fällt kein guter Grund dafür ein.

Ticket Attribute

sind optional und können verwendet werden, um Einstellungen für neu erstellte Tickets vorzunehmen (z.B. den Besitzer, die Gruppe, die Priorität oder den Status festzulegen).

Wenn Sie Ihr Checkmk-Warnskript anpassen wollen, können Sie dies mit diesen tun. Fügen Sie einfach eine zusätzliche „form“-Option für jede dieser Optionen (-F "key=value") in die curl-Befehlszeile Ihres Skripts ein, wie im obigen Beispiel.

Hinweis

💡 Es ist nur ein API-Endpunkt!

Wenn Sie die Checkmk-Integration verwenden, müssen die Nachrichten auf eine bestimmte Art und Weise formatiert werden, aber das bedeutet nicht, dass die Nachrichten tatsächlich von Checkmk kommen müssen.

Wenn Sie ein anderes Monitoring-Tool verwenden, das nicht offiziell von Zammad unterstützt wird, gibt es wahrscheinlich eine Möglichkeit, es mit Ihrer Checkmk-Callback-URL zum Laufen zu bringen.

Checkmk-Parameter

Wenn eine Benachrichtigung eingeht, erstellt Zammad einen neuen Artikel mit den Einzelheiten des Ereignisses, das die Benachrichtigung ausgelöst hat:

Checkmk Artikelinhalt

Diese Angaben stammen aus den unten aufgeführten Feldern, die den von Checkmk bereitgestellten Parametern entsprechen ($NOTIFY_*).

Erforderliche Felder sind mit einem Stern (*) gekennzeichnet.

event_id*

Eine eindeutige ID für das Systemereignis. ($NOTIFY_SERVICEPROBLEMID / $NOTIFY_HOSTPROBLEMID)

host*

Der Hostname des Systems, von dem das Ereignis ausgeht. ($NOTIFY_HOSTNAME)

Wird verwendet, um festzustellen, ob ein neues Ereignis zu einem bestehenden Ticket gehört. Wird auch in der Betreffzeile des resultierenden Artikels verwendet („<Host> ist <Status>“).

service

Der Name des Dienstes, von dem das Ereignis ausgeht. ($NOTIFY_SERVICEDESC)

Wird verwendet, um festzustellen, ob ein neues Ereignis zu einem bestehenden Ticket gehört.

Wird als - angezeigt, wenn es weggelassen wird.

state*

Der aktuelle Zustand des entsprechenden Dienstes oder Hosts. ($NOTIFY_SERVICESTATE / $NOTIFY_HOSTSTATE)

Wird verwendet, um zu erkennen, wann ein Ticket automatisch geschlossen werden soll (d.h. bei OK/UP). Wird auch in der Betreffzeile des resultierenden Artikels verwendet („<Host> ist <Status>“).

text

Die Ausgabe des Prozesses, der das Ereignis ausgelöst hat. ($NOTIFY_SERVICEOUTPUT / $NOTIFY_HOSTOUTPUT)

Wird als - angezeigt, wenn es weggelassen wird.

Ticket Attribute

Die Attributeinstellungen des Objektmanagers zeigen integrierte und benutzerdefinierte Attributnamen an.

Eine vollständige Liste der Ticketattribute finden Sie im Objektmanager.

Ticket-Attribute sind völlig optional und können verwendet werden, um die Tickets, die Checkmk erstellt, individuell zu gestalten. (Beachten Sie, dass diese Attribute ignoriert werden, wenn ein neues Ereignis zu einem bestehenden Ticket erstellt wird.)

Warum sollten Sie das tun? Vielleicht haben Sie nur einen IT-Mitarbeiter, dem alle Probleme bei der Systemüberwachung automatisch zugewiesen werden sollen. Oder vielleicht erstellen Sie mehrere Benachrichtigungsregeln, so dass Datenbankausfälle höhere Priorität haben als Speicherplatzwarnungen.

In den meisten Fällen werden Sie wahrscheinlich eine der folgenden Einstellungen vornehmen wollen:

  • Gruppe

  • Besitzer

  • Status

  • Priorität

aber in der Praxis können Sie fast jedes Attribut setzen, einschließlich benutzerdefinierter Attribute, die Sie über den Objektmanager erstellt haben.

Bitte beachten Sie, dass die folgenden Attribute nicht angepasst werden können:

  • title

  • id

  • ticket number

  • customer

  • created_by_id

  • updated_by_id

Wie finde ich heraus, welche Werte gesetzt werden können?

Warnung

😵 Ungültige Werte → unvorhersehbares Verhalten

Wenn Sie einen Wert angeben, den Zammad nicht versteht (z.B. -F "priority=high"), ist nicht immer klar, was passieren wird. In einigen Fällen wird ein Ticket stattdessen mit den Standardwerten erstellt - in anderen Fällen wird es aber vielleicht gar nicht erstellt!

Welche Werte versteht Zammad denn nun? Nun, das kommt darauf an…

Besitzer

Verwenden Sie eine E-Mail-Adresse oder einen Benutzernamen:

-F "owner=it@chrispresso.com"
Gruppe & Priorität

Beachten Sie die Dropdown-Menüs im Ticketbereich:

-F "group=Users"
-F "priority=3 high"
Siehe mögliche Werte für bestimmte Attribute im Ticketbereich.

Bemerkung

🙅 Der Ticketstatus kann auf diese Weise NICHT eingestellt werden!

Warum? Weil -F "state=..." bereits als ein Checkmk-Parameter verwendet wird.

Alles andere

Um andere Attribute zu setzen, hilft es, sich in der rails console auszukennen. Gültige Werte sind diejenigen, die Sie mit einer Zeichenkette setzen können:

# valid
>> Ticket.first.update(note: "You're gonna need a bigger boat")
=> true
>> Ticket.first.note
=> "You're gonna need a bigger boat"

>> Ticket::State.find_by(name: "open").id
=> 2
>> Ticket.first.update(state_id: 2)
=> true
>> Ticket.first.state.name
=> "open"

# invalid
>> Ticket.first.update(preferences: "I'm a Checkmk ticket!")
=> true
>> Ticket.first.preferences
=> {}

Diese Werte können dann direkt an die API übergeben werden:

-F "note=You're gonna need a bigger boat"
-F "state_id=2"