Script Expressions

Script Expressions enable writing your own custom scripts to be used in complex evaluation scenarios in comparison to regular Event Rules. The scripting language to be used is Javascript.

Features

With Script Expressions some of the problems that you can solve are:

  • Combine complex AND/OR evaluations since it is possible to use multiple variables in a single expression.
  • Preserve data between evaluations, and base the result of the current evaluation on a combination of current and historical data.

Setup

To use Script Expressions, follow these steps:

1. In SiteAdmin, go to Applications > Manage Applications and click in your application name.

2. In the section Privileges and Features > Events > _EditScriptExpression.

3. Save the application properties.

Setting up your Script Expression

1. Login to your Application

2. Go to Admin > Event Rules

3. Select + New Event Rule to create a new event rule.

4. When you reach 4. Expressions, select Script Expression

5. Click in Edit to open the script editor

6. Start developing your scripts. We recommend to follow these guidelines regarding scripting development in GpsGate.

7. When you're done with your script, click in Test Script.

8. Save your script.

9. Save your Event Rule.

To take into consideration

  • It is only possible to add one Script Expression per Event Rule
  • Script Expressions are not available in end expressions. This is not a limitation, since a single script allows you to control conditions for triggering and ending the event in fine detail.
  • Script Expressions should return the result convertible to boolean type (true or false), denoting whether this condition for triggering the event is fulfilled. Note: returning values 0, empty string, null or undefined, or script throwing an error is equivalent to returning false, while returning non-zero values or defined objects is equivalent to true.
  • You can use fields.get(...) function to get values of variables mapped in step “3. Mapping” of the Device Mapper. The first parameter is the variable name, the second parameter is a default value that can be used if the variable does not exist (eg. if the device has never sent it). You should always handle this “missing variable” case to avoid evaluation errors. Note that used variables should be mapped for devices to which the Event Rule will be applied. Scripted variables mapped in step “4. Scripts” of the Device Mapper are accessible from Script Expression scripts.
  • You can use context.setState(...) to set the context.state object accessible from the script, which is preserved between separate evaluations. The parameter of setState can be any value or object defined in the script. State will be saved in JSON format. Note: JSON distinguishes only between Number, String, Boolean, Array, Object or null types; for types such as Date type information will be lost, while functions cannot be saved to state.
  • You can access track point data through the trackPoint object, e.g. as
    var foo = trackPoint.position.longitude;
  • Try to write efficient code and avoid unnecessary instructions in the scripts.
  • There is an execution step limit for each script to prevent bad scripts from crashing the server.

Examples

  • Create a notification when the speed of a vehicle changes. This could be useful if you want to use it to know if the vehicle gets out of an Idle position.

var velocity = trackPoint.velocity.groundSpeed;
var oldvelocity = context.state;
log('velocity: '+velocity);
log('oldvelocity: '+oldvelocity);

if (velocity !== oldvelocity)
{
context.setState(velocity);
return true;
} else return false;

  • Know when a vehicle is speeding only when speeding is happening continuously, over several received messages, for example, three times in a row.

We will use the trackPoint object to access speed data (trackPoint.velocity.groundSpeed) and context.state object to preserve information between evaluations.

To check the speed, and if it crosses the threshold for the first time, we save the information that it happened once, but don’t trigger the event. If it happens again, we have the information that it already happened once in the state object, and we update the state to denote the critical level, but still don’t trigger the event. If it happens the third time, we will see that the state is on critical, and now we will trigger the event.

Finally, if, at any point, the speed goes under the limit, we need to reset the state. We can use a script that looks like this:

var speedLimit = 23; // speed in meters/second

if(trackPoint.velocity.groundSpeed > speedLimit){
// speed is over the limit

if(context.state == 'once') {
context.setState('critical');
return false;
}
else if (context.state == 'critical') {
return true;
}
else {
context.setState('once');
return false;
}
}
else {
// speed is not over the limit
context.setState('');
return false;
}

  • Calculate the time difference between messages

The following script will get triggered when the difference in time between two different device position reports is surpassed.

var d = new Date(trackPoint.utcTimestamp);
var newTime = d.getTime();
var oldTime = context.state;
var limit = 5000; //time in milliseconds

log('newTime: ' + newTime);
log('oldTime: ' + oldTime);

if (!context.state)
{
context.setState (newTime);
log('check1');
}

if ((newTime - oldTime) > limit) // if it's more than the limit then this expression should be true
{
return true;
log('check2');
} else {

context.setState (newTime);
log('check3');
return false;
}

Note: The Event Rule cannot be saved if the script contains errors.

More on Testing

  • Use the log() function to produce debug information in the script editor output in test mode.
  • Use SimOne to generate data for your tests. You can read more about this tool here.
  • You can use the Terminal to view how the data is exchanged between server and tracker. You can read more about using Terminal here.