Click Scripts: trigger custom HTTP requests when a geofence changes

Click Scripts for geofences enable you to trigger custom HTTP requests whenever an operator creates, modifies or removes a geofence.

When a user modifies a geofence, a Click Script for geofences can access the data of that geofence and see the type of action that was performed. With this information, you can create HTTP GET or POST requests, forwarding the information in custom format composed within the script, enabling you to integrate your application with your own web services. Furthermore, a geofence modification is performed only if the script is successfully executed to make sure that the data is forwarded accurately and completely, as defined by the script.

To successfully utilize HTTP requests, it is assumed that you know how to set up and use web services, or at least have an existing web service where the format of data it can receive and interpret correctly is known.

To be able to create Click Scripts, you need to enable _EditClickScript privilege. To do this, follow these steps:

1. Access the application privileges and features.

2. Under ScriptApp section, check all privileges.

3. Login to your Application.

4. From the main menu, go to Admin > Roles.

5. In the Roles window, click on the role for which you want to enable Click Scripts.

Under 2. Privileges, enable ScriptApps privileges in the same way you did for the application.

1. To add a click script, go to Admin > Development > App Builder. This will show you a list of your Apps.

2. Click on an +App to create a new one.

3. Set a name and an optional description, select the _Administrator user, and click on Save.

4. Click on + Click Script button

5. Set a name to your new script, select Geofence, and click on Edit.

Here you should specify a name for the new Click Script. Choose the “Geofence” kind. “Enabled” option determines whether the script will be executed on actual geofence modifications. “Edit” button will take you to the “Script Editor” window.

The auto-generated script on the left is there to show the basic way of handling different geofence operations. On the right, you can see the objects and methods available in Click Scripts for geofences:

• geofence stores geofence information - geofence.name is the name of the geofence, etc (point the cursor to a particular item in the object tree to get more information).
• click.operation stores the information on the performed action.
• http.GET(url,query) and http.POST(url,body) are methods used to execute http requests. After one of those is invoked, response data can be read from http.statusCode, http.statusMessage and http.response.
• log(x) can be used to log data from the script for testing purposes.

Basic scenario: we want to send the information about each updated or removed geofence to a web service.

1. Set up a web service to receive post requests. In this example, the request body is expected to contain a JSON representation of an object containing the information on the action performed and the geofence it was performed on, similar to this:
    

   {   "operation":"Add",   "geofence":     {       "name":"circularGeofence1",       "type":"CircularGeofence",       "center":         {           "longitude":1.234,           "latitude":5.678,           "altitude":0         },         "vertices":null,         "radius":90.123      } }

2. Go to “Admin” ? “Click Scripts”, and add a new Click Script, naming it, for example, “ForwardGeofenceData”. Leave it enabled, and click “Edit” to enter the script editor.

3. Delete the default script, and replace it with:

   var body = '{"operation":"'+click.operation+'","geofence":'+geofence+'}'; http.POST('ADDRESS_OF_YOUR_SERVICE', body);

   In the first line, you format the body in the described format. Note that geofence object is automatically converted into JSON representation when used like this.
   In the second line, ADDRESS_OF_YOUR_SERVICE should be the address of the web service you have set up.

4. Click “Test Script” to execute a test run of the script. Note that this will send the actual request, so you will have to handle and clean up test data manually. Furthermore, to successfully execute a test, you have to select an existing geofence in the Geofence panel. That will be the geofence that the test run will be executed for, i.e. the data of that geofence will be available to the script.
   Finally, note that the test run simulates the situation where a selected type of operation was performed on the selected geofence, but it does not alter the geofence in any way.

5. If the run was successful, the output panel of the editor will contain only the timestamp. If it fails, it will contain text of the error. If you use the log() function anywhere in the script, it will also contain the data you have logged for test purposes. You may also check the HTTP response and status of the last successful request in the appropriate fields in the script editor.
6. Accept and Save the script. Note that if you modified the script after the last test run, you will be prompted to run the script once more when saving. This does not ensure that the script will always be executed successfully, but it helps prevent saving the scripts with evident syntax errors.
7. Try to add, edit, or remove a geofence. If the operation was successful, the web service should have received the request.

Here are hints on some other things you could do:

• You might want to format the data in a different format. You could do this by using JavaScript string formatting options, and accessing geofence fields directly, such as using geofence.center.longitude to get the longitude of the center point of a circular geofence. In that case, make sure to handle the possibility that a geofence might not be circular, in which case the geofence.center property is null, and the use of geofence.center.longitude would make the script fail, preventing the addition or modification of all but circular types of geofences.
• You could set up the service and the script to work in multiple steps, and/or make the script execution dynamic based on the response body received back from the service. This would be performed by a combination of http.GET / http.POSTrequests and reading and interpreting the body of the http.response string. Make sure, however, that the script is always accurately synchronized with the service, as the failing script would prevent the geofence modification.

You may enable the log function and logging of errors from Click Scripts at runtime by editing the NLog.config file in the IIS folder under the GpsGate Server installation folder (if you are not hosting your own server, you may contact support for access to files).
Under <targets>, you should add a new target entry like this:

where TARGET_NAME is a unique name for the file target and FILE_NAME is the name of the log file you wish to be created with a full path to the file.
Under <rules>, add an entry like this:

Where NAME_OF_CLICK_SCRIPT is the name of the click script which you want logged to the file, and TARGET_NAME is the unique name of the target you added above.
Errors and data logged through log method in that Click Script will then be written to the specified file.