Riferimento API

Per la maggior parte degli utenti, gli script di esempio dalla Guida all’installazione faranno il lavoro. Ma se desideri un controllo più granulare, ad esempio per creare ticket ad alta e bassa priorità per diversi tipi di eventi di sistema, dovrai personalizzare i dati che tali script inviano a Zammad.

Esempio

Questo script personalizzato imposterà automaticamente tutti i ticket che crea su alta priorità e li assegnerà a charlie@chrispresso.com.

#!/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/...

Come Funziona?

Ci sono due tipi di dati che puoi passare all’API, entrambi sotto forma di coppie chiave-valore:

Parametri Checkmk

sono richiesti e costituiscono il contenuto dei ticket/articoli risultanti. Determinano anche se un evento crea un nuovo ticket o aggiorna/chiude uno esistente.

Questi sono gli unici valori utilizzati negli script di esempio. Usali così come sono; tecnicamente, possono essere personalizzati, ma è difficile immaginare una buona ragione per farlo.

Attributi del ticket

sono opzionali e possono essere utilizzati per regolare le impostazioni sui ticket appena creati (ad es., impostare il proprietario, il gruppo, la priorità o lo stato).

Se vuoi personalizzare il tuo script di allarme Checkmk, fallo con questi. Aggiungi semplicemente un’opzione «form» extra per ciascuno (-F "chiave=valore") alla riga di comando curl del tuo script, come nell’esempio sopra.

Suggerimento

💡 È solo un endpoint API!

Quando si utilizza l’integrazione Checkmk, i messaggi devono essere formattati in un certo modo, ma ciò non significa che i messaggi debbano provenire effettivamente da Checkmk.

Se utilizzi un altro strumento di monitoraggio non ufficialmente supportato da Zammad, probabilmente c’è un modo per farlo funzionare con il tuo URL di callback Checkmk.

Parametri Checkmk

Quando viene ricevuta una notifica, Zammad crea un nuovo articolo contenente i dettagli dell’evento che l’ha attivata:

Questi dettagli provengono dai campi elencati di seguito, che corrispondono ai parametri forniti da Checkmk ($NOTIFY_*).

I campi obbligatori sono contrassegnati da un asterisco (*).

event_id*

Un ID univoco per l’evento di sistema. ($NOTIFY_SERVICEPROBLEMID / $NOTIFY_HOSTPROBLEMID)

host*

Il nome host del sistema da cui è originato l’evento. ($NOTIFY_HOSTNAME)

Utilizzato per determinare se un nuovo evento appartiene a un ticket esistente. Utilizzato anche nella riga dell’oggetto dell’articolo risultante (“<host> è <state>”).

servizio

Il nome del servizio da cui è originato l’evento. ($NOTIFY_SERVICEDESC)

Utilizzato per determinare se un nuovo evento appartiene a un ticket esistente.

Visualizzato come - quando omesso.

stato*

Lo stato attuale del servizio o host in questione. ($NOTIFY_SERVICESTATE / $NOTIFY_HOSTSTATE)

Utilizzato per rilevare quando un ticket dovrebbe essere chiuso automaticamente (cioè su OK/UP). Utilizzato anche nella riga dell’oggetto dell’articolo risultante (“<host> è <state>”).

testo

L’output del processo che ha attivato l’evento. ($NOTIFY_SERVICEOUTPUT / $NOTIFY_HOSTOUTPUT)

Visualizzato come - quando omesso.

Attributi del Ticket

Trova un elenco completo degli attributi dei ticket nell’Object Manager.

Gli attributi dei ticket sono completamente opzionali e possono essere utilizzati per personalizzare i ticket che Checkmk crea. (Nota che questi attributi verranno ignorati se un nuovo evento appartiene a un ticket esistente.)

Perché vorresti farlo? Forse hai un solo tecnico IT e tutti i problemi di monitoraggio del sistema dovrebbero essergli assegnati automaticamente. Oppure, forse stai creando regole di notifica multiple in modo che i guasti del database abbiano una priorità più alta rispetto agli avvisi di spazio su disco.

Nella maggior parte dei casi, probabilmente vorrai impostare uno dei seguenti:

• gruppo

• proprietario

• stato

• priorità

ma in pratica, puoi impostare quasi tutti gli attributi, inclusi quelli personalizzati che hai creato tramite l’Object Manager.

Si prega di notare che i seguenti attributi non sono personalizzabili:

• titolo

• id

• numero ticket

• cliente

• creato_da_id

• aggiornato_da_id

Quali Valori Possono Essere Impostati?

Avvertimento

😵 Valori non validi → comportamento imprevedibile

Se fornisci un valore che Zammad non comprende (ad es., -F "priority=high"), non è sempre chiaro cosa succederà. In alcuni casi, verrà creato un ticket con i valori predefiniti, ma in altri potrebbe non essere creato affatto!

Quindi, quali valori Zammad comprende? Beh, dipende…

proprietario

Usa un indirizzo email o un nome utente:

-F "owner=it@chrispresso.com"

gruppo e priorità

Fai riferimento ai menu a discesa nel pannello del ticket:

-F "group=Users"
-F "priority=3 high"

Nota

🙅 Lo stato del ticket NON PUÒ essere impostato in questo modo!

Perché? Perché -F "state=..." è già utilizzato come parametro Checkmk.

Tutto il Resto

Per impostare altri attributi, è utile conoscere la console rails. I valori validi sono quelli che puoi impostare con una stringa:

# 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
=> {}

Questi valori possono quindi essere passati direttamente all’API:

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