Filtering content items by location
Inspectors usually work on the object they are standing in front of. If your content type contains hundreds of buildings, scrolling through all of them to find that one building is tedious and error-prone.
With the location filter you can use the current position of the device inside a content item query. That way the iCL Filler can show only those items that are near the inspector, and it can sort the list so that the closest item comes first.
This guide builds on our knowledge base articles about content types and on scripting databound answers.
How it works
The location filter combines two pieces of information:
- the coordinates stored on the content item - a field of your content type that contains the position of the building, the elevator, the fire extinguisher, ... . This data comes from iCL Portal.
- the current position of the device - the iCL Filler asks the operating system for the current GPS position when it runs the query.
From those two, the app calculates the distance in meters and uses it like any other value in the query: as a filter ("not further away than 500 meters") and/or as a sort criterion ("closest one first").
The distance is the direct ("as the crow flies") distance between the two coordinates. It is not a route or a walking distance, so it does not take streets, buildings or floors into account.
iCL Portal: preparing the data
The location filter only works with items whose coordinates are known, so this is where every location-based workbook starts.
Store the coordinates on the content item
Add a field to your content type that holds the position of the item and make sure the items in iCL Portal have that field filled. You can maintain the values like any other content item data - by editing the item in iCL Portal, by importing them from an Excel workbook or via the content items API.
The following value formats are understood:
| Format | Example |
|---|---|
| latitude, longitude | 48.1995789, 16.3863483 |
| latitude, longitude with accuracy | 48.1995789, 16.3863483 (± 178m) |
| WKT point (longitude first!) | POINT (16.3863483 48.1995789) |
Both . and , are accepted as decimal separator, and latitude/longitude are given in decimal degrees (WGS 84) -
the same format you get when you copy a position out of Google Maps. A plain text field is enough for this: the
only thing that matters is that the value has one of the shapes above.
If the form of your content type uses a geolocation field, the inspectors can capture the current position of an item directly in the iCL Filler while they create or edit that item. The app then writes the value including its accuracy, as in the second row of the table above.
An item whose location field is empty or cannot be read is treated as infinitely far away. It will never match a distance filter, and when sorting ascending it ends up at the very end of the list. So before you roll out a location filter, make sure the data is complete - otherwise your inspectors will simply not find those items anymore.
Only synchronized items can be found
The query runs on the device, against the content items that have been synchronized to it. iCL Portal itself never evaluates the location filter. An item that is not part of the device's synchronization scope is not found, no matter how close the inspector is standing to it.
If your inspectors do not see items they expect, check the synchronization rules of the content type first.
iCL Designer: defining the query
The location filter is built from two blockly blocks that live in the queries category of the toolbox.
| Block | Function |
|---|---|
 | Keeps only those content items whose distance to the current position fulfills the comparison. Available operators: <, >, <=, >=. |
 | Sorts the content items by their distance to the current position. ascending puts the closest item first. |
In both blocks the drop-down lists all fields of the content type - pick the field that holds the coordinates (see above). The value of the filter block is a number of meters; you can use a plain number block, or any other block that returns a number, for example the answer of a checklist field.
You can combine the blocks with all the other query blocks. A typical query keeps the items within a radius and sorts them, so the nearest one is on top:
Where you can use the blocks
The two blocks are available in every scriptable property that builds a content item query:
| Property | Where to find it | What it does |
|---|---|---|
| Filter | Content type with Is inspected enabled | Limits the items the inspector can choose from when starting an inspection. |
| Filter | Field of type Content Item | Limits the items the inspector can choose from when filling that field. |
| Query | Field with Has data-bound values, bound to content items | Limits and sorts the available answers of that field. |
| Query | Checklist / chapter / headline with Repeat for related items | Limits and sorts the repeated sections. |
iCL Filler 2 cannot evaluate a location filter. As long as Filler 2 compatibility is enabled in the workbook settings, iCL Designer reports every use of the two blocks as a validation error, and double-clicking the error takes you to the property that uses it.
To use the feature, disable Filler 2 compatibility - the iWorkbook then targets iCL Filler 3 only.
iCL Filler: what the inspector sees
Whenever a list of content items is opened for a query that filters by distance, the app resolves the current position first. While it does so, the list shows "Retrieving location…".
Distance of every item
Each entry of the list shows how far away it is, below its title - for example Distance - 250m. Distances of 1000 m and more are shown in kilometers with one decimal place (Distance - 1.2km).
No results
If nothing is near enough, the list shows "No results found" together with the radius of the query ("You must be within 500m"). This tells the inspector that the list is not empty because there is no data, but because they are too far away.
The location cannot be determined
Location services can be switched off, the app may not have the permission, or the device may simply not get a fix. In that case the app does not show an empty list - that would look like "there is nothing near you". Instead it shows "Location unavailable" with the hint to enable location services and an Open settings button that takes the inspector straight to the relevant system settings page.
Search and barcode scanning stay usable, but they cannot return any result while the position is unknown. Use the refresh action of the list once the setting has been corrected: it asks for the permission again and reloads the list.
The app asks for the location permission the first time a location-filtered list is opened. Make sure your inspectors grant it - ideally while they still have a good connection and are not in a hurry.
Moving while the list is open
The app keeps listening to the position while the list is open. When the inspector moves, a notification appears: "Location Changed - Update search results with new location?" with an Update Search action. The list is deliberately not reloaded automatically, so an entry does not disappear from under the inspector's finger while they are tapping it.
Testing a location filter at your desk
Walking to every content item just to check a query is not practical, so the iCL Filler can pretend to be somewhere else.
Turn on Enable developer mode in the developer options at the bottom of the
iCL Filler settings. A pin button then appears next to the barcode button of
every content item list. It opens a small input field that takes a latitude, longitude pair - exactly what you
get when you right-click a place in Google Maps and copy its coordinates.
As long as a value is entered, the app uses it instead of the real GPS position: the distances are recalculated and the list offers Update Search, just as it does for a real movement. While the overwrite is active the app stops listening to the device's location services; clear the field to hand control back to them.
Latitude and longitude are separated by a comma, so the decimal separator has to be a point
(48.199822, 16.387398). That is the format Google Maps copies to the clipboard.
Good to know
- Keep the content type below 10,000 items. A distance comparison has no SQL equivalent, so the query cannot be answered by the content item index of the app. Instead the app loads every non-deleted item of the content type and evaluates the distance in memory. Once that candidate set reaches the "Maximum number of results that can be returned by a content item query" limit - 10,000 items by default - the list stays empty and reports that the query returns too many results. Additional filters in the query do not help against this, because they are applied only after the items have been loaded; the count is the size of the whole content type. Only a tighter synchronization scope brings it down.
- Choose a generous radius. GPS accuracy varies a lot: between buildings or indoors, a position can easily be off by several tens of meters. A radius that is too small makes items disappear at exactly the moment the inspector needs them.
- Sorting alone is more forgiving than filtering. If the position cannot be resolved, a query that only sorts by distance still returns its items (in an arbitrary order), while a query that filters by distance returns nothing and raises the Location unavailable screen. If in doubt, sorting by distance already gives the inspector most of the benefit.