Ereignisbehandlung

Die Ereignisbehandlung bietet Ihnen die Möglichkeit bei bestimmten Ereignissen vordefinierte Aktionen auszulösen. Für einfache Signale können vordefinierte Aktionstypen wie SMS oder Email genutzt werden. Bei komplexeren Aktionen bietet Protegear auch Webhooks an, d.h. es wird eine URL im Internet aufgerufen und via POST werden die Daten des Ereignisses übergeben.

Nutzen Sie das Symbol um einen neuen Handler zu erstellen oder klicken Sie auf einen Handler um ihn zu bearbeiten.

Basisdaten

Jeder Handler besitzt neben einem Namen und einer Beschreibung auch einen Schalter, der den Handler aktiviert. Nur aktive Handler werden vom System ausgeführt.

In der Liste der Event-Codes können Sie auswählen, bei welchen Ereignissen der Handler ausgelöst werden soll. Sie können hier mehrere Codes auswählen oder den Eintrag - all -, welcher alle Ereignisse selektiert.

Info

Der Ereigniscode POSITION wird nur beim Handler-Typ Webhook ausgewertet, da bei Geräten mit sehr kurzen Zeitintervallen u.U. zu viele Mails oder SMS verschickt werden könnten.

Geräteliste

Am Ende der Seite legen Sie noch fest, für welche Geräte der Handler ausgelöst werden soll. Sie können hier ein oder mehrere Geräte auswählen.

Inhalt

Sie können bei jedem Handler die Daten festlegen, welche übergeben werden. Dazu können Sie den Content der Nachricht mit Hilfe von Go Templates dynamisch gestalten.

Jedes Template bekommt hierzu die Daten des Events und des Geräts in den Feldern .Information, Contacts, .Event sowie .Device übergeben. Da die Template-Sprache von go genutzt wird, müssen Sie für den Zugriff auf Felder diese Feldnamen kennen.

Das .Information Feld beinhaltet die Daten welche in den Einstellunge der Organsation im Feld Information gespeichert sind.

Bei den .Contacts handelt es sich um die Liste der Kontakte, welche in der Protegear Konsole gepflegt werden. Die Reihenfolge ist undefiniert, d.h. es gibt keine spezielle Sortierung. Ein Kontakt hat folgende Datenstruktur:

type Contact struct {
    ID            string    `json:"id"`
    Name          string    `json:"name"`
    Description   string    `json:"description"`
    Created       time.Time `json:"created"`
    LastChange    time.Time `json:"lastchange"`
    LastChangedBy string    `json:"lastchangedBy"`
    OrgID         string    `json:"orgid"`
    Phone         string    `json:"phone"`
    SMS           string    `json:"sms"`
    EMail         string    `json:"email"`
    Address       Address   `json:"address"`
}
type Address struct {
    Appendix    string `json:"appendix"`
    Street      string `json:"street"`
    Number      string `json:"number"`
    City        string `json:"city"`
    State       string `json:"state"`
    Zip         string `json:"zip"`
    CountryCode string `json:"countrycode"`
    Timezone    string `json:"timezone"`
}

Die Datenstruktur für Device ist folgendermaßen:

type Device struct {
    ID                string              `json:"id"`
    SecondaryID       string              `json:"secondary_id"`
    Name              string              `json:"name"`
    Changed           time.Time           `json:"changed"`
    ChangedBy         string              `json:"changedBy"`
    Type              DeviceType          `json:"type"`
    Organization      string              `json:"organization"`
    Comment           string              `json:"comment"`
    ContractID        string              `json:"contractid"`
    Rate              DeviceRate          `json:"rate"`
    Firmware          string              `json:"firmware"`
    Configuration     DeviceConfiguration `json:"configuration"`
    Status            DeviceStatus        `json:"status"`
    EventLifetimeDays int                 `json:"eventLifetimeDays"`
}
type DeviceConfiguration struct {
    Activation      ActivationType `json:"activation"`
    GSM             bool           `json:"gsm"`
    Satellite       bool           `json:"satellite"`
    RescueService   bool           `json:"rescueService"`
    RescueType      RescueType     `json:"rescueType"`
    ReceiveMessages bool           `json:"receiveMessages"`
}
type DeviceRate struct {
    Active   string `json:"active"`
    Inactive string `json:"inactive"`
}
type DeviceStatus string
type ActivationType string
type RescueType string

Ein Event hat folgende Struktur:

type Event struct {
    IMEI        string           `json:"imei"`
    Sent        time.Time        `json:"sent"`
    Received    time.Time        `json:"received"`
    Code        EventCode        `json:"code"`
    DeviceCode  int              `json:"deviceCode,omitempty"`
    DeviceEvent string           `json:"deviceEvent"`
    Text        string           `json:"text,omitempty"`
    Position    *PositionInfo    `json:"position,omitempty"`
    Addresses   []string         `json:"addresses,omitempty"`
    Battery     *BatteryInfo     `json:"battery,omitempty"`
    Info        *EventInfo       `json:"info,omitempty"`
    State       *DeviceInfo      `json:"state,omitempty"`
    Crash       *CrashInfo       `json:"crash,omitempty"`
    Environment *EnvironmentData `json:"environment,omitempty"`
    Type        string           `json:"type,omitempty"`
    Source      EventChannel     `json:"source,omitempty"`
}
type PositionInfo struct {
    Invalid         bool        `json:"invalid"`
    Latitude        float64     `json:"lat"`
    Longitude       float64     `json:"lng"`
    Altitude        int         `json:"alt"`
    Height          int         `json:"height"`
    Gpsfix          int         `json:"gpsfix"`
    NumSatellites   int         `json:"numsatellites"`
    Course          int         `json:"course"`
    SpeedKmH        float64     `json:"speedkmh"`
    VerticalSpeedMs float64     `json:"verticalspeedms"`
    MotionlessSec   int         `json:"motionless"`
    HDOP            float64     `json:"hdop"`
    VDOP            float64     `json:"vdop"`
    Pos6D           *Position6D `json:"pos6d,omitempty"`
}
type BatteryInfo struct {
    LoadInPercent int     `json:"loadpercent"`
    Low           bool    `json:"low"`
    LoadVoltage   float64 `json:"loadvoltage"`
}
type EventInfo struct {
    Intervall int `json:"intervall"`
}
type DeviceInfo struct {
    SOS InfoState `json:"sos"`
}
type CrashVector struct {
    X float64 `json:"x"`
    Y float64 `json:"y"`
    Z float64 `json:"z"`
}

type CrashInfo struct {
    Acceleration []CrashVector `json:"acceleration"`
}
type EnvironmentData struct {
    Temperature *int `json:"temperature,omitempty"`
    AirPressure *int `json:"airpressure,omitempty"`
}
type Position6D string
type EventChannel string
type EventCode string

Beispiel

SOS Benachrichtung

Um bei einem SOS-Event eine EMail zu versenden, können Sie folgenden Code verwenden:

Subject-Template:

SOS from {{.Device.Name}} ({{.Device.ID}})

Body-Template:

Emergency Info: {{.Information}}
<hr size="1"/>
Please get in touch with the following contacts:
<table>
{{ range .Contacts }}
  <tr><td>Name:</td><td>{{.Name}}</td></tr>
  <tr><td>SMS:</td><td>{{.SMS}}</td></tr>
  <tr><td>EMail:</td><td>{{.EMail}}</td></tr>
  <tr><td colspan="2"><hr size="1"/></td></tr>
{{ end }}
</table>

Handler Typ

Es werden verschiedene Typen von Handlern unterschieden. Jeder Handler-Typ hat seine eigenen Einstellungen.

EMail

EMail Handler senden eine EMail, wenn eines Ereignis eintritt. Sie legen im Handler den Empfänger, den Betreff und den Inhalt der EMail fest.

Wenn Sie eine Globalmail Adresse nutzen, kann der Handler die zum Gerät gehörende EMail als Absenderadresse nutzen, wenn Sie diese Option selektieren.

SMS

Ähnlich wie bei der EMail-Nachricht können Sie auch eine SMS versenden. Hier kann der Text der Nachricht auch Variablen enthalten. Beachten Sie, dass eine SMS nur 160 Zeichen enthalten kann und die Nummer des Empfänger im internationalen Format angegeben werden muss.

!!! info “Hinweis” Bitte beachten Sie, dass jede SMS Nachricht Kosten verursacht, die Ihr Konto belasten.

Telegram

Telegram Handler senden eine Nachricht an einen Telegram-Chat. Dazu müssen Sie die Chat-ID angeben sowie den @ProtegearBot zu Ihrer Chat-Gruppe hinzufügen. Durch das Kommando /chatid können Sie den Bot nach der korrekten Chat-ID fragen.

Telegram unterstützt einen Subset von HTML Tags die Sie nutzen können. Es ist empfehlenswert so wenig Formatierung wie möglich zu nutzen, da bei nicht unterstützten Tags/Formaten diese Nachrichten von Telegram abgelehnt werden.

Slack

Slack Handler senden eine Nachricht an einen Slack channel. Dazu müssen Sie die Webhook URL des Channels angeben.

Webhook

Ein Webhook ist eine URL die im Internet bei einem Server Ihrer Wahl terminiert. Sie können hier jede gewünschte URL angeben die Sie möchten.

Sie sollten die Werte bei Rate limit und Concurrency normalerweise nicht ändern. Mit diesen Werten können Sie die Anzahl der gleichzeitigen Requests begrenzen, die zu Ihrem Server gesendet werden bzw. die Anzahl der Requests pro Sekunde. Die Defaultwerte sollten für die meisten Anwendungsfälle ausreichend sein. Wenn Sie jedoch spezielle Anforderungen haben, können Sie diese Werte ändern. Sollten Sie mit sehr hocher Last rechnen, nehmen Sie bitte Kontakt mit unserem Support auf, der Sie hier unterstützen kann.

Um eine gewisse Sicherheit zu gewährleisten bieten sich folgende Optionen an:

• Geben Sie eine URL an, welche spezielle Paramter beinhaltet, die nur Sie kennen und die Sie an Ihrem Server überprüfen
• Geben Sie im Feld Headers Werte an, die unser System dann als HTTP-Header mit zu Ihrem Server sendet. Im Gegensatz zu URL-Parametern sind Header-Paramter normalerweise nicht in Logs zu sehen.
• Nutzen Sie einen HMAC mit einem geheimen Schlüssel. Sie können dann mit ein paar Zeilen Code prüfen, ob der bei Ihnen eingehende Request von Protegear gesendet wurde.

Sollte Ihr Server ein unsicheres Zertifikat besitzen (selfsigned), so aktivieren Sie bitte den Schalter Skip TLS Check.

Warning

Das Ausschalten des TLS Checks ist nur für Test/Entwicklung anzuraten. In produktiven Systemen sollte der Check immer aktiviert sein.

Dem Webhook wird immer eine Liste von Events übergeben. Im Gegensatz zu den anderen Handlern gibt es hier keine Templates o.ä. Stattdessen wird bei eingehenden Events der Hook aufgerufen. Es ist jedoch nicht sichergestellt, dass ein Webhook immer genau einen Event beinhaltet. Wenn viele Events vorliegen, so kann das System diese auch als Batch senden. Ihr Webhook muss also immer eine Liste von Datensätzen verarbeiten; bei sehr wenig Last wird diese Liste meist auch nur aus einem Element bestehen.

Webhook testen

Mit dem Knopf Send Test Message können Sie jederzeit den Webhook mit einem Dummy-Event testen.

Alternativ können Sie auch reale Daten an Ihr System senden. Selektieren Sie hierzu ein Begin- und Ende-Datum. Protegear wird dann die Events aus diesem Zeitraum selektieren und an Ihren Webhook senden. Sie können mit Count Events vorab zählen, wieviele Events in unserer Datenbank dem Kriterium entsprechen und erst dann mit Push Events die Daten senden. Mit dem Batch limit legen Sie fest, wieviel maximale Events pro Request transportiert werden.