HTTP Expression

HTTP Expression can be used to include custom expression in Event Rules. Both in Live Event Rules and Event Rules used for Reporting (Analyze). Another area of usage is to get real time position updates from GpsGate to another system.

GpsGate will make a HTTP request to a URL specified by you. The URL contains complete time, position, variables and user information. Your service response if the expression evaluates to true or false, and it can also include notification variables.

E.g. you have a database of different speed limits for different roads and you want an Event Rules which generates an alarm if a specific speed limit is broken. GpsGate makes a HTTP request for each position update, your service makes a look up in the database and returns true or false depending on if the speed limit was broken or not.

This guide assumes you are familiar with how to manage Plugins, Applications and Event Rules in GpsGate.

Install and activate

1. Go to SiteAdmin > Plugins > Get More Plugins

2. Install Http Expression

3. Enable Http Expression for your application under SiteAdmin > Applications > [click in your app] > Privileges and Features

Setup Event Rule

Inside the VehicleTracker application create an Event Rule, in Step 4 add an "Http Expression".

The "Url" field is the URL to your web service. E.g. http://myserver.com/eventrule.php

Request URL

Example of request URL

http://myserver.com/eventrule.php?POS_LATITUDE=56.09899&POS_LONGITUDE=18&POS_ALTITUDE=0&POS_TIME=2012-12-11T20:49:18&POS_HEADING=180&POS_VALID=True&USER_USERNAME=1111&SIGNAL_SOS=False&SIGNAL_SPEED=0&SIGNAL_BARCODE=Driver1&Aircondition=True

Description of variables

POS_LATITUDE, POS_LONGITUDE is position in decimal degrees.
POS_TIME time in UTC/GMT
POS_HEADING heading in degrees. 0 is north.
POS_VALID True if position was up to date at POS_TIME.
USER_USERNAME user in GpsGate.
SIGNAL_SPEED speed in meters per second.
SIGNAL_BARCODE example of variable from device mapper.

Response XML

Your web service should response with XML in the following format

Code: Select all

<HttpExpression>
    <Result>1</Result>
</HttpExpression>

Result = 1 if expression is true, and 0 if false.

Testing

Use the "Test Settings" button. It will display the request URL, and the response from your web service. If there are any errors those will be written in clear text.

For run time testing use SimOne
http://forum.gpsgate.com/topic.asp?TOPIC_ID=14038

Advanced features

Which most developers won't care about...

Methods test/live/buffer/report

The request URL includes a method= variable which can be test, live, buffer or report.

method=test - The request was made using the Test Settings button.
method=live - Live Gate Message from tracker going forward in time.
method=buffer - Buffered data from device.
method=report - Reporting/Analyze mode.

You can enable the buffer and report methods under "Advanced". By default those methods are disabled.

Notifier variables

Enable "Support notifiers" under "Advanced".

Response XML example with one notifier variable:

Code: Select all

<HttpExpression>
    <Result>0</Result>
    <Notification>
        <Variable>
            <Name>Hello</Name>
            <Value>Hello World!</Value>
            <Type>System.String</Type>
        </Variable>
    </Notification>
</HttpExpression>

Error handling

If the web service times out, returns a HTTP error or invalid XML the connection to the device will be closed. Devices/protocols that requires an ACK will typically resend the same data again until success.

Timeout and parallel requests

Under Advanced set "Request timeout", which is the time before GpsGate will consider the request to be a time out. 

"Max connections" the number of parallel requests that are allowed to be made to your web service.

Asynchronous requests

By default HTTP Expression will make the request once the message comes in from the device. If the request fails, for example if the 3rd party server is down or overloaded, then the connection to the device is closed. If the device has a resend mechanism, it will later try to resend the message. This mode is required for HTTP Expression to work as part of a Live Event Rule.

In case you do not need HTTP Expression to be part of any live events, but rather just use it to forward live tracking data to a 3rd party server, you can instead have HTTP Expression send data asynchronously. You enable this under "Advanced" options. If the 3rd party server fails to respond, HTTP Expression will later resend the request, but the connection to the device is not affected.

Extra variables in request URL

You can add custom variables to the service URL. E.g. http://myserver.com/eventrule.php?myvalue=6