Event handling

Event handling gives you the option of triggering predefined events for certain events Trigger actions. For simple signals, predefined action types such as SMS or e-mail can be used. For more complex actions, Protegear also offers Webhooks, i.e. a URL is called up on the Internet and via POST the Transfer event data.

Use the symbol to create a new handler or click on a handler to edit it.

Basic data

In addition to a name and a description, each handler also has a switch that activates the handler. Only active handlers are executed by the system.

In the list of event codes, you can select the events for which the handler should be triggered. You can select several codes here or the entry - all -, which selects all events.

Info

The event code POSITION is only evaluated for the handler type Webhook, as with devices too many emails or text messages could be sent at very short intervals.

Device list

At the bottom of the page, specify the devices for which the handler should be triggered. You can select one or more devices here.

Content

You can define the data to be transferred for each handler. To do this, you can the content of the message using Go Templates dynamic design.

Each template receives the event and device data in the .Information fields, Contacts, .Event and .Device are transferred. As the template language of go is used, you need to know these field names to access fields.

The .Information Field contains the data that is stored in the organisation’s settings in the Field Information are saved.

The .Contacts is the list of contacts that are stored in the Protegear Console can be maintained. The sequence is undefined, i.e. there is no special Sorting. A contact has the following data structure:

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"`
}

The data structure for Device is as follows:_~go 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

An event has the following structure:~~~go
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

Example

SOS notification

To send an e-mail in the event of an SOS event, you can use the following code:

Subject template:_~

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

Body template:~~~

Emergency Info: {{.Information}}

{{ with .Event.Position }}
<hr size="1"/>
Lat: {{.Latitude}}<br/>
Lng: {{.Longitude}}<br/>
{{ end }}

<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 type

A distinction is made between different types of handlers. Each handler type has its own Settings.

EMail

Email handlers send an email when an event occurs. In the handler, you define the Recipient, the subject and the content of the email.

If you use a globalmail address, the handler can use the email address associated with the device as the sender address if you select this option.

SMS

Similar to the e-mail message, you can also send an SMS. Here you can the text of the message may also contain variables. Please note that an SMS can only contain 160 characters and the number of the recipient in the international Format must be specified.

Note

Please note that every SMS message incurs costs which your Debit account.

Telegram

Telegram handlers send a message to a Telegram chat. To do this, you must enter the chat ID and the @ProtegearBot to your chat group. You can use the /chatid command to add the bot to your chat group ask for the correct chat ID.

Telegram supports a subset of HTML tags that you can use. It is it is advisable to use as little formatting as possible, because if the formatting is not supported tags/formats, these messages will be rejected by Telegram.

Slack

Slack handlers send a message to a Slack channel. To do this, you must enter the webhook URL of the channel.

Webhook

A webhook is a URL that terminates on the Internet at a server of your choice. You you can enter any URL you want here.

You should not normally change the values for Rate limit and Concurrency. You can use these values to limit the number of simultaneous requests that are sent to your server or the number of requests per second. The default values should be sufficient for most applications. However, if you require special Requirements, you can change these values. If you are working with a very high load please contact our support team, who will be able to assist you.

The following options are available to ensure a certain level of security:

• Enter a URL that contains special parameters that only you know and that Check on your server
• Enter values in the field Headers Field, which our system will then send as HTTP headers to To your server. In contrast to URL parameters, header parameters are normally not to be seen in logs.
• Use an HMAC with a secret key. You can then use a few lines Code check whether the key you have incoming request was sent by Protegear.

If your server has an insecure certificate (selfsigned), please activate the Skip TLS Check switch.

Warning

Switching off the TLS check is only recommended for testing/development. In productive Systems, the check should always be activated.

A list of events is always passed to the webhook. In contrast to the other handlers, there are no templates or similar. Instead, the hook is called for incoming events. It is however, it is not guaranteed that a webhook always contains exactly one event. If if there are many events, the system can also send them as a batch. Your webhook must therefore always process a list of data records; if the load is very low, this list is List usually consists of only one element.

Test Webhook

You can use the Send Test Message button to link the webhook to a dummy event at any time test.

Alternatively, you can also send real data to your system. To do this, select a Start and end date. Protegear will then select the events from this period and to your webhook. You can use Count Events to count in advance how many events in of our database match the criterion and only then with Push Events the data send. Use the Batch limit to specify the maximum number of events per request be transported.