Command notifier: send events to your business system

With a Command Notifier, you can signal a custom server over HTTP when something happens in GpsGate. For example, you can let GpsGate send a signal to your business system using event rules when a condition exists (e.g. when a asset enters a geofence, a driver sends SOS, or a logs in using an IButton).

How to set up the Command Notifier

Make sure you're familiar with event rules creation first.

1. When creating your event rule, on step 5. Notifications add a Command notifier.

mceclip1.png

2. Select Custom Server in the first dropdown.

3. Let the second dropdown keep its value _ExternalNotification.

4. Select http in the third dropdown.

5. Enter the URL to your custom server in the URL text field e.g. http://yourserver.com/yourpage.aspx

mceclip2.png

TCP connection: the command notifier can also send outgoing commands using TCP, in which case it uses the GpsGate Protocol. It can also be used to send back Template Commands to a GPS tracker.

6. Click Next

7. Don't select anything on 6. Presentation mode.

8. Save your event rule.

Result

When the Event Rule turns true, GpsGate will make an HTTP GET to the URL you specified.

HTTP request answer

GpsGate makes an HTTP GET to the custom server when the Event Rule is true. The URL will contain all the information you need about the event. Here is an example of an SOS signal:

http://yourserver.com/yourpage.aspx?cmd=_ExternalNotification&SIGNAL_SOS=true&RULE_NAME=SOS&EVENT_TIME=2010-10-03T15:02:56&EVENT_DURATION=0&USER_USERNAME=johan&USER_NAME=johan&USER_DESCRIPTION=&POS_TIME=2010-10-03T15:02:55&POS_LATITUDE=59.28687&POS_LONGITUDE=18.08927&POS_HEADING=275&POS_ADDRESS=Nyn%C3%A4sv%C3%A4gen%20303-305,%20122%2034%20Stockholm,%20Sweden

The value of all GpsGate Variables used in evaluating the event will be included in the URL. They will be named SIGNAL_NAME, where NAME is the upper case variable name (i.e. the variable speed will be named SIGNAL_SPEED).

The following variables are always included in the URL:

  • RULE_NAME
  • EVENT_TIME
  • EVENT_DURATION
  • USER_USERNAME
  • USER_NAME
  • USER_DESCRIPTION
  • POS_TIME
  • POS_LATITUDE
  • POS_LONGITUDE
  • POS_HEADING
  • POS_ADDRESS

If geofence expressions are used, you will find the geofence name in the variable GEOFENCE_NAME.

Reply to HTTP request

Your server must return a plain text OK. Any other kind of reply will be considered to be an error.

Auto-Disable

The system will disable Event Rule HTTP notifier (Command Notifier -> Custom Server -> http) if there are 10 consecutive notification failures within a 10 minute period. And re-enabling the notifier after 10 minutes.

Troubleshooting

You can see the status of the notifier in the Queue Viewer. Log in to Site Admin and take a look under Terminal > Queue Viewer > Commands. If you don’t have a login to Site Admin, please ask your GpsGate Server administrator to enable the Terminal in your Asset Tracker application.

If the HTTP GET fails, GpsGate will retry in 2 minutes, and then every 15 minutes for about 8 hours before there is a permanent failure. The most common problems are that you don’t return a plain text OK, the specified URL is wrong, or you have an exception in the receiving web page. In most cases, the Queue Viewer will give you the information you need to resolve the problem.