Link Scripts

We are introducing Links, a new framework for connecting vehicles with items or users through time. While it was already possible to link a driver to a vehicle using Event Rules, Link Scripts enable tracking passengers, cargo, or any other custom kind of association of an item to a vehicle where the target information denotes that an “item was somehow connected to the vehicle from (start time) to (end time)”.


To install and enable Link Scripts

  1. Navigate to Application > Search and Manage and select a VehicleTracker application of your choice.
  2. Under Privileges and Features, enable the privileges under the Links folder.

  3. Open the application and a new menu item Links will be available.


While you can write your own Link Scripts from scratch, in this guide we will use the default script provided with the Wireless Links plugin.

To install the Wireless Links plugin

  1. Login to SiteAdmin > Plugins tab.
  2. Go to Get More Plugins > Wireless Links and install it.

If you have followed all the steps above, when you open the VehicleTracker application for which you enabled the Links privileges, clicking Links>Link Scripts will show the default Wireless Links script _WirelessLinksRFID. You may click on it to review the script.

Wireless Links Script
The goal of this script is to relay the the information on the RFID tags currently in range of the device to the server.

As we can see, the script uses variables RFID_AttachedRFID_Detached and RFID. Therefore, they need to be mapped for devices which will be using this script.
For Wireless Links devices, this is done by mapping the device inputs RFID_AttachedRFID_Detached and RFID to the corresponding variables.

This script expects the following behavior by the device:

  • when a new RFID tag is detected, the device sends a message with RFID_Attached=true and RFID=(id of tag). When we detect this case, a link action is executed.
  • when a tag is no longer in range, the device sends a message with RFID_Detached=true and RFID=(id of tag). When we detect this case, an unlink action is executed.

Note that link/unlink actions require a namespace to be specified. These namespaces serve to describe the nature of the link (e.g. whether it is cargo, passenger, driver, etc.). “_Cargo” namespace used here is one of the default namespaces provided.
You can view existing or add new namespaces through Links > Namespaces.

link namespaces
Finally, to enable the script, set Enabled to Yes, and then navigate to the Tags panel of the Edit Link Script window and choose the tags that will denote the users for which the script will be executed.

Link Tags
Link data can be reviewed in the window accessible through Links > Browse Links. Specify search criteria and click Next to view results.

links browse

Created link items can be reviewed in the window accessible through Links > Link Items. You may edit custom names of the existing items, create new items manually or delete items (this will delete their link data, too).

link items

Useful Notes

  • Default Link Scripts cannot be modified. They can only be enabled or disabled for a set of tags. You can use the Create Copy button to copy the script, modify it and save it with a different name.
  • Consult the object tree in the script editor for more information on the available functions, such as loading users for linking to vehicles (session.directory.getLinkableUser(id)), checking if a variable value was changed (fields.revised(strName)))

Reprocessing

If you install the Developer Tools plugin, you may reprocess link data for the selected application, namespace, users and period. In SiteAdmin, go to Reporting > Reprocess and select Links.

More on Testing

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 log the data from the script to the editor or terminal window using log(valueOrObject) function. 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.
Finally, use the _Test namespace provided (or create another one for this purpose) to test the script with real devices to make sure that the scripts are executed efficiently and with expected results.

Links in Reports

Following link-related functions are available in report layout.

Function Description Example
$getlinks(namespace, vehicle, timestamp) Returns a comma-delimited list of link names attached to the vehicle specified by ID, within specified namespace, at the specified timestamp. $getlinks(_CARGO, [UserID], [SamplingStart])
$getlinkcount(namespace, vehicle, timestamp) Returns the count of linkable items attached to the vehicle specified by ID, within specified namespace, at the specified timestamp. $getlinkcount(_CARGO, [UserID], [SamplingStart])
$linkname(identifier) Returns the name of the linkable item (Link Item or User) associated to the specified string identifier (data like Driver ID from fields such as RFID, IButton…). $linkname([EventArgument])

Here is a more comprehensive example of using link scripts with reports.

  1. Lets say that we’re using the default _WirelessLinksRFID script modified to work with users instead of items (the line with session.directory.getLinkItem should be modified to use session.directory.getLinkableUser(id) instead), and with ‘_Passenger’ namespace instead of ‘_Cargo’. Name the new Link Script, for example, PassengerLinks.
  2. Create an Event Rule (named, e.g. LinkHelperRule) triggered whenever RFID_Attached or RFID_Detached is true (two digital expressions, matching any) as a one-shot event (the same two digital expressions added as end expressions after clicking “Show advanced options” in Expressions section of the Event Rule, also matching any).
  3. We create a new report based on EV1000 Event Rule report, like in the image below. simple links reportNote that the cell in Links column contains $getlinks(_Passenger,[UserID],[SamplingStart]) Change the grouping by right clicking on any of the the pink headers of the group rows, choosing Edit Group, and using [Name] for both grouping and sorting. Activate and configure this report for the application in which you created the PassengerLinks and the LinkHelperRule.
  4. Run the report for LinkHelperRule. The result should look like this. simple links result