Script Notifiers

Note: Script Notifiers are deprecated. We recommend that you use Icon Notifiers combined with a Script Expression instead.

Using JavaScript and GpsGate Scripting API, you can create fully customizable event notifiers. 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 a vehicle’s marker on the map to different icons for different speed intervals.

First, enable the _EditScriptNotifier privilege. In order to do this, follow these steps:

1. Log in to Site Admin.
2. Go to the Applications tab. Click Search and Manage.
3. Click on the application for which you want to enable the script notifiers.
4. Scroll down to the Privileges and Rules section. Under Events in the tree, check _EditScriptNotifier and click Save. This will enable script notifiers for the _Administrator role.
5. Log in to the Vehicle Tracker Application. From the main menu, go to “Admin” ⇒ “Roles”.
6. In the 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.

Now that you have enabled script notifiers, let's create one. Script notifiers, like 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, you first have to open the “Event Rule” window in your Vehicle Tracker Application:

1. Log in to the 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 the “+” (plus) button to add a new notifier.
4. Select “Client Script” from the list.
5. In the form displayed, you can click “Edit” to open the script editor. The multi-select dropdown labeled “Run this when” lets you pick when the notifier should be executed.

There are a few things you should be aware of before 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.

Things to consider 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 the $END function here if you want to get the updated speed value continuously in the event pending state. Please check this article to get more information about argument notifiers.

  

• Scripting: After creating the argument notifiers for the inputs, you need to save the event rule to register the arguments in the database. Then you can go back to the “Event Rule” window to continue with scripting. The 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.

  

• GpsGate Scripting API: The tree view to the right of script editor shows the GpsGate Scripting API namespaces, functions, and input parameters you defined. Note that only the “Core” namespace is available in the scripting context by default, and the other namespaces need to be imported. Unavailable namespaces will appear grayed out. They will turn active once you import them using the dropdown 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 explanations.

  

• Importing namespaces: Select the namespaces you want to use in your code, then click the “+” (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.

  

• 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.

  var speed = Core.resolveInput('Speed');

• Debugging: Debugging allows you to test your code by specifying the input parameters, and running them in the test mode. In this mode, the script will take effect 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.

  

• 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.

For our first case, we want to create an event rule that sets the 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:

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

The components needed for the event rule are:

It’s always useful to debug your code before saving it in order to see if the code generates different results for different cases. If different results are generated, be sure to check:

• if you have a syntax error,
• if you imported the 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 the browser’s JavaScript console. Also, it might help to check the server log files for server-side errors.