Scripting, previously introduced for Device Mapper variables, is now available for Event Rule expressions as well. Script Expressions enable writing complex expressions in an integrated and intuitive way.
To use Script Expressions, follow these steps:
- Log in to SiteAdmin.
- Go to the Plugins tab.
- Under My Plugins tab, make sure all plugins are up to date.
- In your application properties, make sure you have enabled _EditScriptExpression privilege.
With Script Expressions, it is possible to base the condition for triggering the event on complex equations involving more than one variable, as in Device Mapper Scripting. As a reminder, some of the problems that scripts can solve are:
- Inverting a boolean variable.
- Using more than one input variable to produce one output variable.
- Extracting bits from an accumulated variable.
- Assigning text values to a set of value ranges when each range indicates a specific status.
Script Expressions are more powerful than the old way of combining Expressions with “AND”/“OR” since it is possible to use multiple variables in a single expression.
Furthermore, with Script Expressions you can preserve data between evaluations, and base the result of the current evaluation on a combination of current and historical data. Finally, track point data for the user has been made accessible from the script.
When creating an Event Rule, choose Script Expression in step 4. Expressions, as shown below. The _EditScriptExpression privilege (under Events) is required in order for the Script Expression to be available in the list of expressions.
Note: It is only possible to add one Script Expression per Event Rule and 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.
Once you select the Script Expression in the list of expressions, you will be presented with the Script Expression entry, as shown below.
Clicking Edit leads you to the Script Editor window. If you are familiar with Device Mapper Scripting, you will recognize this view (shown below) and notice some new features.
Good to know
- 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.
Adding a Script Expression
Let us create an Event Rule based on a Script Expression. Consider the scenario: we want to know when a vehicle is speeding. However, we do not want to be alerted by every short breach of the speed limit, but only when speeding is happening continuously, over several received messages, for example, three times in a row.
1) Go to Admin → Event Rules, and click on Add new Event Rule.
2) Name the rule, for example, “Long Speeding”, and continue to step “4. Expressions”.
3) Add a Script Expression, and click Edit.
4) To achieve our goal, we will use the trackPoint object to access speed data (trackPoint.velocity.groundSpeed) and context.state object to preserve information between evaluations.
5) The idea is 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. The final script looks like this:
6) You can run the script by clicking the Test Script button. If you enter value 24 for groundSpeed and run the script, value of state will change to “once” (immediately visible in text box under state), and the output will be Expression evaluates to: False. Running again will have the same output, but change the state to “critical”. After the third run, state will remain the same, and test output will be Expression evaluates to: True.
Another way of solving the same problem would be by using the mapped Speed variable, accessible via fields.get(“Speed”,0) (instead of using trackPoint.velocity.groundSpeed). In that case, you could test the output by selecting Speed in the list of variables under fields in the list of exposed objects on the right, and clicking Add, which adds Speed to the list of variables available for testing. After adding variables to the list, check those that you want to use, and edit the test values.
The Script in the Script Editor window is synchronized with the Event Rule window, so, when done editing and/or testing, just close the Script Editor and continue editing the Event Rule.
Values and variables used in the editor are saved for the current user editing the script when the editor is closed. If the user saves the Event Rule, they will be preserved for when the user edits the same Script Expression again. The Event Rule cannot be saved if the script contains errors.
More on Testing
The log() function provided to produce debug information about script evaluation (to script editor output in test mode, or to terminal window in production), apart from logging primitive values or custom strings, can now be used to log complex objects in JSON format.
When you are writing a new script it is useful to test the script with a device. GpsGate provides a simulator for the “GpsGate TrackerOne” device that can be very helpful during the script development. For more information about SimOne click here.
You can use the Terminal to view how the data is exchanged between server and tracker. It also shows the output value of script mappings for each incoming message.
For more information about the Terminal plugin click here.