Script Notifiers

We are introducing a new and a more flexible way to define event notifiers. Now you can use Script Notifiers to create notifiers using JavaScript and GpsGate Scripting API.


Script Notifiers are a new way to create fully customizable event notifiers using JavaScript language and GpsGate Scripting API. By leveraging this feature, you can make your event rules smarter, simply by handling different states with your own custom code. For instance, you can tell an event rule to set vehicle’s marker on the map to different icons for different speed intervals.

How to install or upgrade the plugin
  1. Login to SiteAdmin.
  2. Go to Plugins tab.
  3. Set the Repository URL to http://update.gpsgate.com
  4. Under My Plugins tab, make sure Patch.v4 plugin is installed and up to date.
Enabling Script Notifiers

Before you can go ahead, you need to enable the _EditScriptNotifier privilege. In order to do this, follow these steps:

  1. Login to SiteAdmin.
  2. Go to Applications tab. Click Search and Manage.
  3. Click on the application you want to enable the script notifiers.
  4. Scroll down to Privileges and Rules section. Under Events in the tree, check _EditScriptNotifier and click Save. This will enable script notifiers for the _Administrator role.
  5. Login to Vehicle Tracker Application. From the main menu, go to “Admin” ⇒ “Roles”.
  6. In Roles window, click on the role you want to enable script notifiers for.
  7. Under Privileges, you can enable script notifiers for that particular role in the same way you did for the application.
Creating Script Notifiers

Now that you have enabled script notifiers, you can go ahead and create one. Script notifiers, as the rest of the event notifiers, must be specified as a part of an event rule.

To add a script notifier to your event rule, first you have to open the “Event Rule” window in your Vehicle Tracker Application:

  1. Login to Vehicle Tracker Application. From the main menu, go to “Admin” ⇒ “Event Rules”.
  2. Select the Event Rule you want to modify, or click “Add new Event Rule” button to create a new one.
  3. Under step 5 (Notifications), click “+” (plus) button to add a new notifier.
  4. From the list, select “Client Script”.
  5. In the form displayed, you can click “Edit” to open script editor. The multi-select drop down labeled “Run this when” lets you pick when the notifier should be executed.

Create Script Notifier

Rules for Scripting

There are a few things you should be aware of before going ahead with writing the script. First of all, the scripting language is JavaScript. However, the script is executed in a different context than the existing window, thus accessing DOM elements or other global variables is not allowed. You are provided with GpsGate Scripting API for this context, along with the input parameters defined in the event rule.

The list below describes things to be taken into consideration when creating a script notifier:

  • Configuring input parameters: Before starting to write your script, you may need input parameters to evaluate the state of the event. You might need to obtain a set of signals from the device in order to determine what should be performed. For script notifiers, you need to do this by using Argument Notifiers. For each input parameter, you need to define an argument notifier with a label that you will use later. The figure below shows an example to obtain the speed data from the device. Please note that you must use $END function here, if you want to get the updated speed value continuously in the event pending state. Please check this blog post to get more information about argument notifiers. The blog post talks about Report Argument Notifiers, which is based on the same logic as Argument Notifiers.

    Arguments

  • Scripting: After creating the argument notifiers for the inputs, you need to save the event rule to register arguments in the database. Then, you can go back to “Event Rule” window to continue with scripting. Script editor opens with a brief guide and a basic code example when opened for the first time. Once you read the guide, feel free to remove the text and start typing your own code.

    Editor

  • GpsGate Scripting API: The tree view to the right of script editor shows the GpsGate Scripting API namespaces, functions and the input parameters you defined. Note that only “Core” namespace is available in the scripting context by default, and the other namespaces need to be imported. Unavailable namespaces will appear grayed out, and they will turn active once you import them using the drop down above the namespace tree.
    Typically, you need to type [Namespace].[Function] in order to invoke an API function. Try pointing your mouse cursor on the API functions on the tree to see more detailed explanation.

    API Tree

  • Importing namespaces: Select the namespaces you want to use in your code, then click “+” (plus) button to import the namespace. Imported namespaces turn active on the tree. You can remove imported namespaces by clicking “-” (minus) icon next to each one in the list above the tree.

    Namespace Import

  • Resolving input parameters: Once registered in the database (by leveraging Argument Notifiers), available input parameters will be appended to the tree structure. In order to resolve an input parameter, you must use “resolveInput” function available under “Core” namespace. Note that resolved values are in SI unit.

  • Debugging: Debugging allows you to test your code by specifying the input parameters, and running it in the test mode. In this mode, script will take affect on the selected vehicle in the “Vehicles” list, and the result is not preserved.

    It might come in handy to use Core.log([Object]) function to print variables on the debugging console.

    Debug mode

  • Execution modes: Don’t forget to specify when your script notifier should be executed. There are three stages of an event (Started, Pending, Finished), and you are allowed to pick multiple values for when the notifier should be run.
Examples

For our first case, we want to create an event rule that sets vehicle marker to a medium speed car icon if the speed is over 10 m/s. If the speed gets over 20 m/s, the event rule should change the marker to a fast car icon. If the speed is below 10 m/s, then the vehicle marker is reset to its initial state.

 

The components needed for the event rule are:

 

Expressions

  1. Analog Expression

    Condition: Speed >= 0.1

Notifications

  1. Argument Notification

    Name: Speed

    Value: $END([SIGNAL_SPEED])

  2. Script Notifier

    Run this when: Start & Pending

    Script:

 

 

For the second case, we would like to change marker color to red if the speed is over 30/ms. Marker color should be set to black when the speed goes down below 30 m/s.

 

The components needed for the event rule are:

 

Expressions

  1. Analog Expression

    Condition: Speed >= 30

Notifications

  1. 1st Script Notifier

    Run this when: Start & Pending

    Script:

  2. 2nd Script Notifier

    Run this when: Finish

    Script:

Troubleshooting

It’s always useful to debug your code before saving it, in order to see if the code generates different results for different cases. First few things to check would be:

  • if you have a syntax error,
  • if you imported required namespaces,
  • if a user is selected in the vehicles list (for debugging mode)

Since the debugging console is not available in the live mode, the errors are printed to browser’s JavaScript console. Also, it might help to check the server log files for server side errors.


  Discuss this blog post on the forum please



Download free GpsGate Server

Install it on your own server. The installation is free for 5 users.

Download Now