How to install or upgrade the plugin
- Log in to SiteAdmin.
- Go to the Plugins tab.
- Under My Plugins tab, make sure all plugins are 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:
- Login to SiteAdmin.
- Go to Applications tab. Click Search and Manage.
- Click on the application you want to enable the script notifiers.
- 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.
- Login to Vehicle Tracker Application. From the main menu, go to “Admin” ⇒ “Roles”.
- In Roles window, click on the role you want to enable script notifiers for.
- 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:
- Login to Vehicle Tracker Application. From the main menu, go to “Admin” ⇒ “Event Rules”.
- Select the Event Rule you want to modify, or click “Add new Event Rule” button to create a new one.
- Under step 5 (Notifications), click “+” (plus) button to add a new notifier.
- From the list, select “Client Script”.
- 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.
Rules for Scripting
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.
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.
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.
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.
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.
- 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 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 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:
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)
Discuss this blog post on the forum please