Link Scripts

Links is a 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)”. 

---

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.

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.

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

As we can see, the script uses variables RFID_Attached, RFID_Detached and RFID. Therefore, they need to be mapped for devices that we will be using this script.
For Wireless Links devices, this is done by mapping the device inputs RFID_Attached, RFID_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.

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 data can be reviewed in the window accessible through Links > Browse Links. Specify search criteria and click Next to view results.

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

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

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.

When you are writing a new script it is useful to test the script with a device. GpsGate provides a device simulator that can be very helpful during script development.
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.

The 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. Let's 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. Note that the cell in Links column contains $getlinks(_Passenger,[UserID],[SamplingStart]) Change the grouping by right-clicking on any of 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.